Re: PQputCopyEnd doesn't adhere to its API contract

On Wed, Sep 3, 2014 at 6:24 PM, Bruce Momjian <bruce@momjian.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@sss.pgh.pa.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