Re: PQputCopyEnd doesn't adhere to its API contract

Robert Haas <robertmhaas(at)gmail(dot)com> writes:
> According to the documentation for PQputCopyEnd:
>> The result is 1 if the termination data was sent, zero if it was not sent because the attempt would block (this case is only possible if the connection is in
>> nonblocking mode), or -1 if an error occurred. (Use PQerrorMessage to retrieve details if the return value is -1. If the value is zero, wait for write-ready and try again.)

> However, pqPutCopyEnd contains no return statement that can ever
> possibly return 0.

IIRC, for some of the libpq functions, the API spec was intended to allow
for future async behavior that wasn't actually implemented. So the mere
fact that it can't return zero today is not a problem. If it might block
instead, then we have a problem, but that's not what you're saying.

Also, what the API spec says is that clients should retry PQputCopyEnd
on a zero return. We do *not* want them to do that here; once we've
changed asyncStatus, a retry would report an error. So the API spec
in this case is intended to require a retry loop that the current
implementation doesn't actually need, but that conceivably could be
needed after some future refactoring. In particular, we might want
to fix the code so that it returns zero if it fails to queue the
COPY END message at all.

> pqFlush() returns 0 if no data is waiting to be sent, or otherwise the
> return value of pqSendSome(). pqSendSome() returns -1 if an error
> occurs, 0 if all data is sent, or 1 if some data was sent but the
> socket is non-blocking and the caller must try again later. It seems
> to me that when pqSendSome() returns 1, pqPutCopyEnd ought to return 0
> in order to meet its API contract - and then the client, presumably,
> should repeatedly wait for the socket to become write-ready and then
> try PQflush() until PQflush() returns non-zero.

That would be a change in the API spec, not just the implementation,
and it's not clear to me that it would actually be helpful to any
clients.

regards, tom lane