37.7. Отмена запросов в процессе выполнения #
Клиентское приложение может запросить отмену команды, которая ещё обрабатывается сервером, используя функции, описанные в этом разделе.
PQgetCancel#Создаёт структуру данных, содержащую информацию, необходимую для отмены команды, запущенной через конкретное подключение к базе данных.
PGcancel *PQgetCancel(PGconn *conn);
Функция
PQgetCancelсоздаёт объектPGcancel, получив объектPGconn, описывающий подключение. Она возвратитNULL, если параметрconnравенNULLили представляет недействительное подключение. ОбъектPGcancelявляется непрозрачной структурой, которая не предназначена для того, чтобы приложение обращалось к ней напрямую; её можно только передавать функцииPQcancelилиPQfreeCancel.PQfreeCancel#Освобождает память, занимаемую структурой данных, созданной функцией
PQgetCancel.void PQfreeCancel(PGcancel *cancel);
PQfreeCancelосвобождает память, занимаемую объектом, предварительно созданным функциейPQgetCancel.PQcancel#Требует, чтобы сервер прекратил обработку текущей команды.
int PQcancel(PGcancel *cancel, char *errbuf, int errbufsize);
Возвращаемое значение равно 1, если запрос на отмену был успешно отправлен, и 0 в противном случае. В случае неудачной отправки
errbufзаполняется пояснительным сообщением об ошибке.errbufдолжен быть массивом символов, имеющим размерerrbufsize(рекомендуемый размер составляет 256 байт).Успешная отправка ещё не является гарантией того, что запрос будет иметь какой-то эффект. Если отмена сработала, текущая команда завершится досрочно и возвратит в качестве результата ошибку. Если же отмена не получится (например, потому, что сервер уже завершил обработку команды), тогда вообще не будет видимого результата.
PQcancelможно безопасно вызывать из обработчика сигнала, еслиerrbufявляется локальной переменной в обработчике сигнала. ОбъектPGcancelдоступен только в режиме чтения, пока речь идёт о функцииPQcancel, поэтому её можно также вызывать из потока, отдельного от того, который управляет объектомPGconn.
PQrequestCancel#PQrequestCancelявляется устаревшим аналогом функцииPQcancel.int PQrequestCancel(PGconn *conn);
Выдаёт запрос на то, чтобы сервер прекратил обработку текущей команды. Функция работает напрямую с объектом
PGconnи в случае сбоя сохраняет сообщение об ошибке в объектеPGconn(откуда его можно извлечь с помощьюPQerrorMessage). Хотя функциональность та же самая, этот подход небезопасен для многопоточных программ или обработчиков сигналов, поскольку перезапись сообщения об ошибке, хранящегося в объектеPGconn, может помешать ходу операции, выполняемой через данное подключение.
37.7. Canceling Queries in Progress #
A client application can request cancellation of a command that is still being processed by the server, using the functions described in this section.
PQgetCancel#Creates a data structure containing the information needed to cancel a command issued through a particular database connection.
PGcancel *PQgetCancel(PGconn *conn);
PQgetCancelcreates aPGcancelobject given aPGconnconnection object. It will returnNULLif the givenconnisNULLor an invalid connection. ThePGcancelobject is an opaque structure that is not meant to be accessed directly by the application; it can only be passed toPQcancelorPQfreeCancel.PQfreeCancel#Frees a data structure created by
PQgetCancel.void PQfreeCancel(PGcancel *cancel);
PQfreeCancelfrees a data object previously created byPQgetCancel.PQcancel#Requests that the server abandon processing of the current command.
int PQcancel(PGcancel *cancel, char *errbuf, int errbufsize);
The return value is 1 if the cancel request was successfully dispatched and 0 if not. If not,
errbufis filled with an explanatory error message.errbufmust be a char array of sizeerrbufsize(the recommended size is 256 bytes).Successful dispatch is no guarantee that the request will have any effect, however. If the cancellation is effective, the current command 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.
PQcancelcan safely be invoked from a signal handler, if theerrbufis a local variable in the signal handler. ThePGcancelobject is read-only as far asPQcancelis concerned, so it can also be invoked from a thread that is separate from the one manipulating thePGconnobject.
PQrequestCancel#PQrequestCancelis a deprecated variant ofPQcancel.int PQrequestCancel(PGconn *conn);
Requests that the server abandon processing of the current command. It operates directly on the
PGconnobject, and in case of failure stores the error message in thePGconnobject (whence it can be retrieved byPQerrorMessage). Although the functionality is the same, this approach is not safe within multiple-thread programs or signal handlers, since it is possible that overwriting thePGconn's error message will mess up the operation currently in progress on the connection.
