Re: PQputCopyEnd doesn't adhere to its API contract

On Thu, May 8, 2014 at 5:21 PM, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:
> Perhaps the text should be like this:
>
> The result is 1 if the termination message was sent; or in nonblocking
> mode, this may only indicate that the termination message was successfully
> queued. (In nonblocking mode, to be certain that the data has been sent,
> you should next wait for write-ready and call <function>PQflush</>,
> repeating until it returns zero.) Zero indicates that the function could
> not queue the termination message because of full buffers; this will only
> happen in nonblocking mode. (In this case, wait for write-ready and try
> the PQputCopyEnd call again.) If a hard error occurs, -1 is returned; you
> can use <function>PQerrorMessage</function> to retrieve details.

That looks pretty good. However, I'm realizing this isn't the only
place where we probably need to clarify the language. Just to take
one example near at hand, PQputCopyData may also return 1 when it's
only queued the data; it seems to try even less hard than PQputCopyEnd
to ensure that the data is actually sent.

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company