Re: PQputCopyEnd doesn't adhere to its API contract

Tom Lane-2 wrote
> Robert Haas <

> robertmhaas@

> > writes:
>> On Thu, May 8, 2014 at 1:51 PM, Tom Lane <

> tgl@.pa

> > wrote:
>>> Robert Haas <

> robertmhaas@

> > 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.

Had trouble comprehending Tom's wording so decided to word-smith a little:

The return value can be one of [-1, 0 , 1] whose meaning depends on whether
you are in blocking or non-blocking mode.  
In blocking mode a 1 means success and -1 means permanent failure; it is not
possible to receive a 0 in blocking mode - all calls will either succeed (1)
or fail (-1).
In non-blocking mode a 1 means that the termination message was placed in
the queue while a -1 means an immediate and permanent failure. A return
value of 0 means that the queue was full and that you need to try again at
the next wait-ready.
[?]While in non-blocking mode once you have received a return value of 1 you
will need to continually poll, at each wait-ready, <function>PQflush</>
until it returns 0 (queue empty) or -1 (failure).
The error associated with the -1 return can be retrieved using
<function>PQerrorMessage</>

[?]Isn't the whole PQflush comment simply repeating what is written
elsewhere?  The requirement is standard when working in non-blocking mode.

It does seem like the "buffer full" case would be fairly direct to
resolve...and I'm not sure what the explanation would be, in the doc above,
as to why "0 is not returned by the current implementation because (the
queue can never be full, or, even in non-blocking mode the system will block
to add to the queue in this function)....

David J.





--
View this message in context:
http://postgresql.1045698.n5.nabble.com/PQputCopyEnd-doesn-t-adhere-to-its-API-contract-tp5803240p5803297.html
Sent from the PostgreSQL - hackers mailing list archive at Nabble.com.