Готовит соединение для отправки запросов отмены.

PGcancelConn *PQcancelCreate(PGconn *conn);

Функция PQcancelCreate создаёт объект PGcancelConn, однако отправка запросов отмены не начинается сразу. Запрос отмены можно отправить через это соединение блокирующим способом, используя PQcancelBlocking, и неблокирующим, используя PQcancelStart. Полученное значение можно передать через PQcancelStatus для проверки, что объект PGcancelConn создан успешно. Объект PGcancelConn является непрозрачной структурой, которая не предполагает доступ напрямую через приложение. Этот объект PGcancelConn можно использовать для потокобезопасной отмены запроса, который выполняется на исходном соединении.

При настройке соединения для отправки запроса отмены переиспользуются многие параметры соединения исходного клиента. Важно помнить, что если исходное соединение требует шифрования соединения и/или проверки целевого узла (через sslmode или gssencmode), то соединение для запроса отмены создаётся с такими же требованиями. Любые параметры соединения, используемые только во время или сразу же после аутентификации клиента, игнорируются, поскольку запросы отмены не требуют аутентификации, а соединение закрывается сразу после отправки запроса отмены.

Заметьте, что если функция PQconnectStart возвращает ненулевой указатель, то, закончив его использование, вы должны вызвать PQcancelFinish, чтобы освободить полученную структуру и все связанные с ней блоки памяти. Это нужно сделать, даже если попытка подключения не последует или окажется неуспешной.

Требует, чтобы сервер прекратил обработку текущей команды блокирующим способом.

int PQcancelBlocking(PGcancelConn *cancelConn);

Запрос отправляется по заданному соединению PGcancelConn, которое необходимо создать функцией PQcancelCreate. PQcancelBlocking возвращает 1, если запрос отмены успешно отправлен, и 0 в противном случае. В случае неудачи сообщение об ошибке можно получить с помощью функции PQcancelErrorMessage .

Успешная отправка отмены ещё не является гарантией того, что запрос будет иметь какой-то эффект. Если отмена сработала, текущая команда завершится досрочно и возвратит в качестве результата ошибку. Если же отмена не получится (например, потому, что сервер уже завершил обработку команды), тогда видимого результата не будет вовсе.

Выдаёт запрос на то, чтобы сервер прерывал выполнение текущей команды неблокирующим способом.

int PQcancelStart(PGcancelConn *cancelConn);

PostgresPollingStatusType PQcancelPoll(PGcancelConn *cancelConn);

Запрос отправляется по заданному соединению PGcancelConn, которое необходимо создать функцией PQcancelCreate. PQcancelStart возвращает 1, если запрос отмены может быть отправлен, и 0 в противном случае. В случае неудачи сообщение об ошибке можно получить с помощью функции PQcancelErrorMessage .

Если вызов PQcancelStart оказался успешным, нужно опросить libpq для продолжения процедуры подключения. Вызовите PQcancelSocket для получения дескриптора нижележащего сокета, через который устанавливается соединение с базой данных. (Внимание: этот сокет может меняться от вызова к вызову PQcancelPoll.) Организуйте цикл таким образом: если PQcancelPoll(cancelConn) при последнем вызове возвращает PGRES_POLLING_READING, ожидайте, пока сокет не окажется готовым для чтения (это покажет функция select(), poll() или подобная системная функция). Затем снова вызовите PQcancelPoll(cancelConn). Если же PQcancelPoll(cancelConn) при последнем вызове возвратила PGRES_POLLING_WRITING, дождитесь готовности сокета к записи, а затем снова вызовите PQcancelPoll(cancelConn). На первой итерации, то есть когда вы ещё не вызывали PQcancelPoll(cancelConn), реализуйте то же поведение, что и после получения PGRES_POLLING_WRITING. Продолжайте этот цикл, пока PQcancelPoll(cancelConn) не выдаст значение PGRES_POLLING_FAILED, сигнализирующее об ошибке при установлении соединения, или PGRES_POLLING_OK, показывающее, что соединение установлено успешно.

Успешная отправка отмены ещё не является гарантией того, что запрос будет иметь какой-то эффект. Если отмена сработала, текущая команда завершится досрочно и возвратит в качестве результата ошибку. Если же отмена не получится (например, потому, что сервер уже завершил обработку команды), тогда видимого результата не будет вовсе.

В любое время в процессе подключения его состояние можно проверить, вызвав PQcancelStatus. Если этот вызов возвратит CONNECTION_BAD, значит, процедура отмены завершилась сбоем; если вызов возвратит CONNECTION_OK, значит, запрос отмены успешно отправлен. Оба эти состояния можно определить на основе возвращаемого значения функции PQcancelPoll, описанной выше. Другие состояния могут также иметь место в течение (и только в течение) асинхронной процедуры подключения. Они показывают текущую стадию процедуры подключения и могут быть полезны, например, для предоставления обратной связи пользователю. Вот эти состояния: