Re: PQputCopyEnd doesn't adhere to its API contract

Robert Haas <robertmhaas(at)gmail(dot)com> writes:
> On Thu, May 8, 2014 at 1:51 PM, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:
>> Robert Haas <robertmhaas(at)gmail(dot)com> writes:
>>> OK. It still seems to me that there's a doc fix needed here, if
>>> nothing else. The documentation for PQputCopyEnd() clearly implies
>>> that if you get a return value of 1, the message is sent, and that's
>>> just not true.

>> That's fair.

> Something like the attached?

> I don't really know what to say about 0, since it's never actually
> returned, so I left that out. But I'm up for suggestions.

I think you should leave the existing verbiage about zero alone.
If we take it out, we're painting ourselves into a corner about
ever fixing the buffer-is-too-full failure case.

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.

If it bothers you to document behavior that's not actually there yet,
maybe you should go fix the bug ;-). I had thought this would require
a lot of refactoring, but it might work to just check if there's enough
buffer space for the message and return zero immediately if not.

regards, tom lane