29.5. Annuler des requêtes en cours d'exécution

Crée une structure de données contenant les informations nécessaires à l'annulation d'une commande lancée sur une connexion particulière à la base de données.

PGcancel *PQgetCancel(PGconn *conn);

PQgetCancel crée un objet fonction PGcancel avec un objet connexion PGconn. Il renverra NULL si le paramètre conn donné est NULL ou est une connexion invalide. L'objet PGcancel est une structure opaque qui n'a pas pour but d'être accédé directement par l'application ; elle peut seulement être passée à PQcancel ou PQfreeCancel.

Libère une structure de données créée par PQgetCancel.

void PQfreeCancel(PGcancel *cancel);

PQfreeCancel libère un objet donné par PQgetCancel.

Demande que le serveur abandonne l'exécution de la commande en cours.

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

La valeur renvoyée est 1 si la demande d'annulation a été correctement envoyée et 0 sinon. Si non, errbuf contient un message d'erreur expliquant pourquoi. errbuf doit être un tableau de caractères d'une taille de errbufsize octets (la taille recommandée est de 256 octets).

Un envoi réussi ne garantie pas que la demande aura un quelconque effet. Si l'annulation est réelle, la commande en cours terminera plus tôt et renverra une erreur. Si l'annulation échoue (disons, parce que le serveur a déjà exécuté la commande), alors il n'y aura aucun résultat visible.

PQcancel peut être invoqué de façon sûr par le gestionnaire de signaux si errbuf est une variable locale dans le gestionnaire de signaux. L'objet PGcancel est en lecture seule pour ce qui concerne PQcancel, pour qu'il puisse aussi être appelé à partir d'un thread séparé de celui manipulant l'objet PGconn.

Demande que le serveur abandonne le traitement de la commande en cours.

int PQrequestCancel(PGconn *conn);

PQrequestCancel est une variante obsolète de PQcancel. Elle opère directement sur l'objet PGconn et, en cas d'échec, stocke le message d'erreur dans l'objet PGconn (d'où il peut être récupéré avec PQerrorMessage). Bien qu'il s'agisse de la même fonctionnalité, cette approche est hasardeuse en cas de programmes compatibles avec les threads ainsi que pour les gestionnaires de signaux car il est possible que la surcharge du message d'erreur de PGconn gênera l'opération en cours sur la connexion.