27.5. Cancelamento de comandos em andamento

Cria uma estrutura de dados contendo as informações necessárias para cancelar um comando enviado através de uma determinada conexão com o banco de dados.

PGcancel *PQgetCancel(PGconn *conn);

A função PQgetCancel cria o objeto PGcancel a partir do objeto de conexão PGconn. Retorna nulo se o parâmetro conn fornecido for nulo, ou se for uma conexão inválida. O objeto PGcancel é uma estrutura opaca que não foi feita para ser acessada diretamente pelo aplicativo; somente pode ser passado para a função PQcancel ou PQfreeCancel.

Libera a estrutura de dados criada pela função PQgetCancel.

void PQfreeCancel(PGcancel *cancel);

A função PQfreeCancel libera o objeto de dados previamente criado pela função PQgetCancel.

Solicita ao servidor que abandone o processamento do comando corrente.

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

O valor retornado será igual a 1 quando o envio da solicitação de cancelamento for bem-sucedido, e 0 caso contrário. Se não for bem-sucedido, o parâmetro errbuf será preenchido com uma mensagem de erro explicando o motivo. O parâmetro errbuf deve ser uma matriz de caracteres do tamanho errbufsize (o tamanho recomendado é de 256 bytes).

Entretanto, o envio bem-sucedido não garante que a solicitação tenha algum efeito. Se o cancelamento for efetivo, o comando corrente termina mais cedo e retorna um resultado de erro. Se o cancelamento falhar (digamos, porque o servidor já tenha terminado de processar o comando), então não haverá nenhum resultado visível.

A função PQcancel pode ser chamada com segurança a partir de um tratador de sinais, se o parâmetro errbuf for uma variável local do tratador de sinais. No que diz respeito à função PQcancel, o objeto PGcancel é apenas para leitura, portanto esta função também pode ser chamada a partir de um fluxo de execução (thread) separado do fluxo de execução que manipula o objeto PGconn.

Solicita ao servidor que abandone o processamento do comando corrente.

int PQrequestCancel(PGconn *conn);

A função PQrequestCancel é uma variante em obsolescência da função PQcancel. Esta função opera diretamente no objeto PGconn, e no caso de falha armazena a mensagem de erro no objeto PGconn (de onde a mensagem pode ser extraída pela função PQerrorMessage). Embora a funcionalidade seja a mesma, esta abordagem cria perigos para programas com vários fluxos de execução e para tratadores de sinais, por ser possível que a sobrescrita da mensagem de erro de PGconn atrapalhe a operação atualmente em andamento na conexão.