29.5. 処理中の問い合わせのキャンセル

特定のデータベース接続を通して発行されたコマンドをキャンセルするために必要な情報を持つデータ構造を作成します。

PGcancel *PQgetCancel(PGconn *conn);

PQgetCancelは、与えられたPGconn接続オブジェクトのPGcancelオブジェクトを作成します。 与えられたconnがNULLもしくは無効な接続であった場合、NULLが返されます。 PGcancelオブジェクトは不透明構造であり、アプリケーションから直接アクセスすることができません。 これはPQcancelもしくはPQfreeCancelに渡すことしかできません。

PQgetCancelで作成されたデータ構造を解放します。

void PQfreeCancel(PGcancel *cancel);

PQfreeCancelは事前にPQgetCancelで作成されたデータオブジェクトを解放します。

サーバに現在のコマンドの廃棄処理を要求します。

int PQcancel(PGcancel *cancel, char *errbuf, int errbufsize);

キャンセル要求の受け入れが成功すれば1を、そうでなければ0を返します。 失敗した場合、errbufにその原因を表すエラーメッセージが収納されます。 errbufはerrbufsizeサイズの文字配列でなければなりません。 (推奨サイズは256バイトです。)

しかし、要求の受け入れが成功したとしても、その要求の効果が出ることは全く保証していません。 もしキャンセル操作が有効であれば、現在のコマンドは間もなく中断され、エラーが結果として返ります。 キャンセル操作に失敗した場合（つまりバックエンドがすでにコマンド処理を終了していたため）、目に見える結果は何も出てこなくなります。

errbufがシグナルハンドラ内のローカル変数であれば、PQrequestCancelはシグナルハンドラから起動しても問題ありません。 PQcancelの実行中、PGcancelは読み取りのみです。 従って、PGconnオブジェクトを操作するスレッドと別のスレッドからこの関数を呼び出すこともできます。

サーバに現在のコマンドの廃棄処理を要求します。

int PQrequestCancel(PGconn *conn);

PQrequestCancelはPQcancelの変形版であり廃止予定です。 これはPGconnオブジェクトを直接扱い、また、失敗した場合エラーメッセージはPGconnオブジェクト内に収納されます。 (PQerrorMessageにより取り出すことができます。) 機能的には同一ですが、PGconnのエラーメッセージが上書きされることにより、その接続で現在進行中の操作が壊れてしまうため、この方法は複数スレッドプログラムやシグナルハンドラでは問題が起こります。