32.7. Canceling Queries in Progress
Prev | Up | Chapter 32. libpq — C Library | Home | Next

## 32.7. Canceling Queries in Progress #

### 32.7.1. Functions for Sending Cancel Requests #

`PQcancelCreate` #

  Prepares a connection over which a cancel request can be sent.

      PGcancelConn *PQcancelCreate(PGconn *conn);

  `PQcancelCreate` creates a `PGcancelConn` object, but it won't instantly start sending a cancel request over this connection. A cancel request can be sent over this connection in a blocking manner using `PQcancelBlocking` and in a non-blocking manner using `PQcancelStart`. The return value can be passed to `PQcancelStatus` to check if the `PGcancelConn` object was created successfully. The `PGcancelConn` object is an opaque structure that is not meant to be accessed directly by the application. This `PGcancelConn` object can be used to cancel the query that's running on the original connection in a thread-safe way.

  Many connection parameters of the original client will be reused when setting up the connection for the cancel request. Importantly, if the original connection requires encryption of the connection and/or verification of the target host (using `sslmode` or `gssencmode`), then the connection for the cancel request is made with these same requirements. Any connection options that are only used during authentication or after authentication of the client are ignored though, because cancellation requests do not require authentication and the connection is closed right after the cancellation request is submitted.

  Note that when `PQcancelCreate` returns a non-null pointer, you must call `PQcancelFinish` when you are finished with it, in order to dispose of the structure and any associated memory blocks. This must be done even if the cancel request failed or was abandoned.

`PQcancelBlocking` #

  Requests that the server abandons processing of the current command in a blocking manner.

      int PQcancelBlocking(PGcancelConn *cancelConn);

  The request is made over the given `PGcancelConn`, which needs to be created with `PQcancelCreate`. The return value of `PQcancelBlocking` is 1 if the cancel request was successfully dispatched and 0 if not. If it was unsuccessful, the error message can be retrieved using `PQcancelErrorMessage` .

  Successful dispatch of the cancellation is no guarantee that the request will have any effect, however. If the cancellation is effective, the command being canceled will terminate early and return an error result. If the cancellation fails (say, because the server was already done processing the command), then there will be no visible result at all.

`PQcancelStart`
`PQcancelPoll` #

  Requests that the server abandons processing of the current command in a non-blocking manner.

      int PQcancelStart(PGcancelConn *cancelConn);

      PostgresPollingStatusType PQcancelPoll(PGcancelConn *cancelConn);

  The request is made over the given `PGcancelConn`, which needs to be created with `PQcancelCreate`. The return value of `PQcancelStart` is 1 if the cancellation request could be started and 0 if not. If it was unsuccessful, the error message can be retrieved using `PQcancelErrorMessage` .

  If `PQcancelStart` succeeds, the next stage is to poll libpq so that it can proceed with the cancel connection sequence. Use `PQcancelSocket` to obtain the descriptor of the socket underlying the database connection. (Caution: do not assume that the socket remains the same across `PQcancelPoll` calls.) Loop thus: If `PQcancelPoll(cancelConn)` last returned `PGRES_POLLING_READING`, wait until the socket is ready to read (as indicated by `select()`, `poll()`, or similar system function). Then call `PQcancelPoll(cancelConn)` again. Conversely, if `PQcancelPoll(cancelConn)` last returned `PGRES_POLLING_WRITING`, wait until the socket is ready to write, then call `PQcancelPoll(cancelConn)` again. On the first iteration, i.e., if you have yet to call `PQcancelPoll(cancelConn)`, behave as if it last returned `PGRES_POLLING_WRITING`. Continue this loop until `PQcancelPoll(cancelConn)` returns `PGRES_POLLING_FAILED`, indicating the connection procedure has failed, or `PGRES_POLLING_OK`, indicating cancel request was successfully dispatched.

  Successful dispatch of the cancellation is no guarantee that the request will have any effect, however. If the cancellation is effective, the command being canceled will terminate early and return an error result. If the cancellation fails (say, because the server was already done processing the command), then there will be no visible result at all.

  At any time during connection, the status of the connection can be checked by calling `PQcancelStatus`. If this call returns `CONNECTION_BAD`, then the cancel procedure has failed; if the call returns `CONNECTION_OK`, then cancel request was successfully dispatched. Both of these states are equally detectable from the return value of `PQcancelPoll`, described above. Other states might also occur during (and only during) an asynchronous connection procedure. These indicate the current stage of the connection procedure and might be useful to provide feedback to the user for example. These statuses are:

  `CONNECTION_ALLOCATED` #

    Waiting for a call to `PQcancelStart` or `PQcancelBlocking`, to actually open the socket. This is the connection state right after calling `PQcancelCreate` or `PQcancelReset`. No connection to the server has been initiated yet at this point. To actually start sending the cancel request use `PQcancelStart` or `PQcancelBlocking`.

  `CONNECTION_STARTED` #

    Waiting for connection to be made.

  `CONNECTION_MADE` #

    Connection OK; waiting to send.

  `CONNECTION_AWAITING_RESPONSE` #

    Waiting for a response from the server.

  `CONNECTION_SSL_STARTUP` #

    Negotiating SSL encryption.

  `CONNECTION_GSS_STARTUP` #

    Negotiating GSS encryption.

  Note that, although these constants will remain (in order to maintain compatibility), an application should never rely upon these occurring in a particular order, or at all, or on the status always being one of these documented values. An application might do something like this:

      switch(PQcancelStatus(conn))
      {
              case CONNECTION_STARTED:
                  feedback = "Connecting...";
                  break;

              case CONNECTION_MADE:
                  feedback = "Connected to server...";
                  break;
      .
      .
      .
              default:
                  feedback = "Connecting...";
      }

  The `connect_timeout` connection parameter is ignored when using `PQcancelPoll`; it is the application's responsibility to decide whether an excessive amount of time has elapsed. Otherwise, `PQcancelStart` followed by a `PQcancelPoll` loop is equivalent to `PQcancelBlocking`.

`PQcancelStatus` #

  Returns the status of the cancel connection.

      ConnStatusType PQcancelStatus(const PGcancelConn *cancelConn);

  The status can be one of a number of values. However, only three of these are seen outside of an asynchronous cancel procedure: `CONNECTION_ALLOCATED`, `CONNECTION_OK` and `CONNECTION_BAD`. The initial state of a `PGcancelConn` that's successfully created using `PQcancelCreate` is `CONNECTION_ALLOCATED`. A cancel request that was successfully dispatched has the status `CONNECTION_OK`. A failed cancel attempt is signaled by status `CONNECTION_BAD`. An OK status will remain so until `PQcancelFinish` or `PQcancelReset` is called.

  See the entry for `PQcancelStart` with regards to other status codes that might be returned.

  Successful dispatch of the cancellation is no guarantee that the request will have any effect, however. If the cancellation is effective, the command being canceled will terminate early and return an error result. If the cancellation fails (say, because the server was already done processing the command), then there will be no visible result at all.

`PQcancelSocket` #

  Obtains the file descriptor number of the cancel connection socket to the server.

      int PQcancelSocket(const PGcancelConn *cancelConn);

  A valid descriptor will be greater than or equal to 0; a result of -1 indicates that no server connection is currently open. This might change as a result of calling any of the functions in this section on the `PGcancelConn` (except for `PQcancelErrorMessage` and `PQcancelSocket` itself).

`PQcancelErrorMessage` #

  Returns the error message most recently generated by an operation on the cancel connection.

      char *PQcancelErrorMessage(const PGcancelConn *cancelconn);

  Nearly all libpq functions that take a `PGcancelConn` will set a message for `PQcancelErrorMessage` if they fail. Note that by libpq convention, a nonempty `PQcancelErrorMessage` result can consist of multiple lines, and will include a trailing newline. The caller should not free the result directly. It will be freed when the associated `PGcancelConn` handle is passed to `PQcancelFinish`. The result string should not be expected to remain the same across operations on the `PGcancelConn` structure.

`PQcancelFinish` #

  Closes the cancel connection (if it did not finish sending the cancel request yet). Also frees memory used by the `PGcancelConn` object.

      void PQcancelFinish(PGcancelConn *cancelConn);

  Note that even if the cancel attempt fails (as indicated by `PQcancelStatus`), the application should call `PQcancelFinish` to free the memory used by the `PGcancelConn` object. The `PGcancelConn` pointer must not be used again after `PQcancelFinish` has been called.

`PQcancelReset` #

  Resets the `PGcancelConn` so it can be reused for a new cancel connection.

      void PQcancelReset(PGcancelConn *cancelConn);

  If the `PGcancelConn` is currently used to send a cancel request, then this connection is closed. It will then prepare the `PGcancelConn` object such that it can be used to send a new cancel request.

  This can be used to create one `PGcancelConn` for a `PGconn` and reuse it multiple times throughout the lifetime of the original `PGconn`.

### 32.7.2. Obsolete Functions for Sending Cancel Requests #

These functions represent older methods of sending cancel requests. Although they still work, they are deprecated due to not sending the cancel requests in an encrypted manner, even when the original connection specified `sslmode` or `gssencmode` to require encryption. Thus these older methods are heavily discouraged from being used in new code, and it is recommended to change existing code to use the new functions instead.

`PQgetCancel` #

  Creates a data structure containing the information needed to cancel a command using `PQcancel`.

      PGcancel *PQgetCancel(PGconn *conn);

  `PQgetCancel` creates a `PGcancel` object given a `PGconn` connection object. It will return `NULL` if the given `conn` is `NULL` or an invalid connection. The `PGcancel` object is an opaque structure that is not meant to be accessed directly by the application; it can only be passed to `PQcancel` or `PQfreeCancel`.

`PQfreeCancel` #

  Frees a data structure created by `PQgetCancel`.

      void PQfreeCancel(PGcancel *cancel);

  `PQfreeCancel` frees a data object previously created by `PQgetCancel`.

`PQcancel` #

  `PQcancel` is a deprecated and insecure variant of `PQcancelBlocking`, but one that can be used safely from within a signal handler.

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

  `PQcancel` only exists because of backwards compatibility reasons. `PQcancelBlocking` should be used instead. The only benefit that `PQcancel` has is that it can be safely invoked from a signal handler, if the `errbuf` is a local variable in the signal handler. However, this is generally not considered a big enough benefit to be worth the security issues that this function has.

  The `PGcancel` object is read-only as far as `PQcancel` is concerned, so it can also be invoked from a thread that is separate from the one manipulating the `PGconn` object.

  The return value of `PQcancel` is 1 if the cancel request was successfully dispatched and 0 if not. If not, `errbuf` is filled with an explanatory error message. `errbuf` must be a char array of size `errbufsize` (the recommended size is 256 bytes).

`PQrequestCancel` #

  `PQrequestCancel` is a deprecated and insecure variant of `PQcancelBlocking`.

      int PQrequestCancel(PGconn *conn);

  `PQrequestCancel` only exists because of backwards compatibility reasons. `PQcancelBlocking` should be used instead. There is no benefit to using `PQrequestCancel` over `PQcancelBlocking`.

  Requests that the server abandon processing of the current command. 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 is not safe within multiple-thread programs or signal handlers, since it is possible that overwriting the `PGconn`'s error message will mess up the operation currently in progress on the connection.

Prev | Up | Next
32.6. Retrieving Query Results in Chunks | Home | 32.8. The Fast-Path Interface