Re: PQputCopyEnd doesn't adhere to its API contract

On Wed, Sep 3, 2014 at 6:24 PM, Bruce Momjian <bruce(at)momjian(dot)us> wrote:
> On Fri, May 9, 2014 at 12:03:36PM -0400, Robert Haas wrote:
>> 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.
>
> Uh, where are we on this?

I think someone needs to take Tom's proposed language and make it into
a patch. And figure out which other functions in the documentation
need similar updates.

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