Подготавливает соединение, через которое может быть отправлен запрос на отмену.

PGcancelConn *PQcancelCreate(PGconn *conn);

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

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

Обратите внимание: если функция PQcancelCreate возвращает ненулевой указатель, необходимо вызвать функцию 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, описанная выше. Другие состояния могут также возникать в процессе (и только в процессе) асинхронной процедура установления соединения. Данные значения указывают на текущий этап процедуры установления соединения и могут быть полезны, например, для обеспечения обратной связи с пользователем. Список возможных статусов:

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

switch(PQcancelStatus(объект conn))
{
        case CONNECTION_STARTED:
            feedback = "Connecting...";
            break;

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

Параметр connect_timeout параметр соединения игнорируется при использовании PQcancelPoll; при этом приложение само должно определить, истекло ли избыточное время ожидания. В противном случае PQcancelStart за которым следует PQcancelPoll цикл эквивалентен PQcancelBlocking.

Функция возвращает статус соединения для отмены запроса.

ConnStatusType PQcancelStatus(const PGcancelConn *cancelConn);

Статус может принимать одно из нескольких значений. Однако только три из них встречаются вне процедуры асинхронной отмены: CONNECTION_ALLOCATED, CONNECTION_OK и CONNECTION_BAD. Начальное состояние PGcancelConn , успешно созданного с помощью функции PQcancelCreate имеет значение NULL CONNECTION_ALLOCATED. Запрос на отмену, который был успешно отправлен, имеет состояние CONNECTION_OK. О неудачной на попытку отмены указывает статус CONNECTION_BAD. Статус OK будет сохраняться до тех пор, пока PQcancelFinish или PQcancelReset вызывается функция.

См. описание для PQcancelStart относительно других кодов состояния, которые могут быть возвращены.

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

Получает номер дескриптора файла сокета для соединения с целью отмены запроса к серверу.

int PQcancelSocket(const PGcancelConn *cancelConn);

Значение корректного дескриптора должно быть больше или равно 0; результат -1 указывает на то, что соединение с сервером в данный момент не открыто. Это значение может измениться в результате вызова любой из функций, описанных в данном разделе, для объекта PGcancelConn (за исключением самой функции PQcancelErrorMessage и PQcancelSocket itself).

Возвращает сообщение об ошибке, которое было последним сгенерировано при выполнении операции над соединением для отмены.

char *PQcancelErrorMessage(const PGcancelConn *cancelconn);

Практически все libpq функции, принимающие PGcancelConn устанавливают сообщение для PQcancelErrorMessage в случае их неудачного завершения. Следует отметить, что согласно libpq соглашению, непустой PQcancelErrorMessage результат может состоять из нескольких строк и включает завершающий символ новой строки. Вызывающая сторона не должна освобождать память результата напрямую. Она будет освобождена, когда соответствующий PGcancelConn идентификатор будет передан функции PQcancelFinish. Не следует ожидать, что содержимое результирующей строки сохранится после выполнения операций над PGcancelConn структурой.

Закрывает соединение для отмены (если отправка запроса на отмену еще не была завершена). Также функция освобождает память, используемую PGcancelConn объект.

void PQcancelFinish(PGcancelConn *cancelConn);

Обратите внимание, что даже если попытка отмены завершилась неудачей (как указывает PQcancelStatus), то приложение должно вызвать PQcancelFinish для освобождения памяти, которую занимает PGcancelConn объект. Параметр PGcancelConn указатель не должен использоваться повторно после PQcancelFinish функция была вызвана.

Сбрасывает PGcancelConn для возможности повторного использования в новом соединении отмены.

void PQcancelReset(PGcancelConn *cancelConn);

Если PGcancelConn в данный момент используется для отправки запроса на отмену, то это соединение закрывается. Затем функция подготовит PGcancelConn объект таким образом, чтобы его можно было использовать для отправки нового запроса на отмену.

Это может быть использовано для создания одного экземпляра PGcancelConn для PGconn с его последующим многократным использованием в течение всего времени существования оригинала PGconn.

Создаёт структуру данных, содержащую информацию, необходимую для отмены команды с использованием PQcancel.

PGcancel *PQgetCancel(PGconn *conn);

PQgetCancel создаёт PGcancel объекта для заданного PGconn объекта соединения. Она возвращает значение NULL если заданный объект conn развертывается значение NULL или недействительное соединение. Параметр PGcancel объект является непрозрачной структурой, к которой не должно быть прямого обращения из приложения; его можно передавать только в PQcancel или PQfreeCancel.

Освобождает структуру данных, созданную функцией PQgetCancel.

void PQfreeCancel(PGcancel *cancel);

PQfreeCancel освобождает объект данных, созданный ранее функцией функцией PQgetCancel.

PQcancel является устаревшим и небезопасным вариантом функции PQcancelBlocking, который, однако, можно безопасно использовать внутри обработчика сигналов.

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

PQcancel существует исключительно по соображениям обратной совместимости. PQcancelBlocking следует использовать вместо неё. Единственным преимуществом, PQcancel которым обладает функция , является возможность её безопасного вызова из обработчика сигналов, если errbuf является локальной переменной в обработчике сигналов. Однако это обычно не считается достаточно весомым преимуществом, чтобы оправдать проблемы с безопасностью данной функции.

Параметр PGcancel объект является доступным только для чтения, поэтому функция также может быть вызвана PQcancel из потока, отличного от того, в котором используется PGconn объект.

Возвращаемым значением функции PQcancel равно 1, если запрос на отмену был успешно отправлен, и 0 — в противном случае. В противном случае параметр errbuf заполняется пояснительным сообщением об ошибке. errbuf должен представлять собой массив типа char размером errbufsize (рекомендуемый размер составляет 256 байт).

PQrequestCancel является устаревшим и небезопасным вариантом функции PQcancelBlocking.

int PQrequestCancel(PGconn *conn);

PQrequestCancel существует исключительно по соображениям обратной совместимости. PQcancelBlocking следует используется вместо неё. Использование ... не дает никаких преимуществ PQrequestCancel по сравнению с PQcancelBlocking.

Запрашивает у сервера прекращение обработки текущей команды. Данная функция работает непосредственно с PGconn объектом conn, и в случае сбоя сохраняет сообщение об ошибке в PGconn объекте conn (откуда оно может быть извлечено функцией PQerrorMessage ). Хотя функциональные возможности идентичны, данный подход не является безопасным в многопоточных программах или обработчиках сигналов, так как существует вероятность, того, что перезапись PGconnсообщения об ошибке объекта conn нарушит операцию, выполняемую в данный момент в рамках соединения.