本節で説明する関数を使用して、クライアントアプリケーションはサーバで処理中のコマンドをキャンセルする要求を行うことができます。
PQgetCancel
特定のデータベース接続を通して発行されたコマンドをキャンセルするために必要な情報を持つデータ構造を作成します。
PGcancel *PQgetCancel(PGconn *conn);
PQgetCancel
は、与えられたPGconn接続オブジェクトのPGcancelオブジェクトを作成します。
与えられたconnがNULLもしくは無効な接続であった場合、NULLが返されます。
PGcancelオブジェクトは不透明な構造体であり、アプリケーションから直接アクセスすることができません。
これはPQcancel
もしくはPQfreeCancel
に渡すことしかできません。
PQfreeCancel
PQgetCancel
で作成されたデータ構造を解放します。
void PQfreeCancel(PGcancel *cancel);
PQfreeCancel
は事前にPQgetCancel
で作成されたデータオブジェクトを解放します。
PQcancel
サーバに現在のコマンドの廃棄処理を要求します。
int PQcancel(PGcancel *cancel, char *errbuf, int errbufsize);
キャンセル要求の受け入れが成功すれば1を、そうでなければ0を返します。 失敗した場合、errbufにその原因を表すエラーメッセージが収納されます。 errbufはerrbufsizeサイズの文字配列でなければなりません。 (推奨サイズは256バイトです。)
しかし、要求の受け入れが成功したとしても、その要求の効果が出ることは全く保証していません。 もしキャンセル操作が有効であれば、現在のコマンドは間もなく中断され、エラーが結果として返ります。 キャンセル操作に失敗した場合(つまりバックエンドがすでにコマンド処理を終了していたため)、目に見える結果は何も出てこなくなります。
errbufがシグナルハンドラ内のローカル変数であれば、PQrequestCancel
はシグナルハンドラから起動しても問題ありません。
PQcancel
の実行中、PGcancelは読み取りのみです。
従って、PGconnオブジェクトを操作するスレッドと別のスレッドからこの関数を呼び出すこともできます。
PQrequestCancel
サーバに現在のコマンドの廃棄処理を要求します。
int PQrequestCancel(PGconn *conn);
PQrequestCancel
はPQcancel
の変形版であり廃止予定です。
これはPGconnオブジェクトを直接扱い、また、失敗した場合エラーメッセージはPGconnオブジェクト内に収納されます。
(PQerrorMessage
により取り出すことができます。)
機能的には同一ですが、PGconnのエラーメッセージが上書きされることにより、その接続で現在進行中の操作が壊れてしまうため、この方法は複数スレッドプログラムやシグナルハンドラでは問題が起こります。