30.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 is a deprecated variant of PQcancel. It operates directly on the PGconn object, and in case of failure stores the error message in the PGconn object (whence it can be retrieved by PQerrorMessage). Although the functionality is the same, this approach creates hazards for multiple-thread programs and signal handlers, since it is possible that overwriting the PGconn's error message will mess up the operation currently in progress on the connection. --> PQrequestCancelはPQcancelの変形版であり廃止予定です。 これはPGconnオブジェクトを直接扱い、また、失敗した場合エラーメッセージはPGconnオブジェクト内に収納されます。 (PQerrorMessageにより取り出すことができます。) 機能的には同一ですが、PGconnのエラーメッセージが上書きされることにより、その接続で現在進行中の操作が壊れてしまうため、この方法は複数スレッドプログラムやシグナルハンドラでは問題が起こります。