Re: PQputCopyEnd doesn't adhere to its API contract - Mailing list pgsql-hackers
On Fri, May 9, 2014 at 12:03:36PM -0400, Robert Haas wrote:Uh, where are we on this?
> On Thu, May 8, 2014 at 5:21 PM, Tom Lane <[hidden email]> 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.
The comment for "PQsetnonblocking" in 31.4 says:
"In the nonblocking state, calls to PQsendQuery, PQputline, PQputnbytes, and PQendcopy will not block but instead return an error if they need to be called again."
This is apparently false for PQendcopy - I did not go look at the others
I stand by my belief that someone who is using "Non-Blocking Mode" on read
should
understand how to proceed if they receive a 1 or 0
result from one of the "put" calls. A cross-reference to the relevant section of the docs may be in order if that assumption is felt to be too optimistic. While it could possibly be more prominent the last sentence in 31.4 states:
"
After sending any command or data on a nonblocking connection, call PQflush. If it returns 1, wait for the socket to be write-ready and call it again; repeat until it returns 0. Once PQflush returns 0, wait for the socket to be read-ready and then read the response as described above. "
That said, I imagine a "tip" section for PQputCopyData may be in order if the caller can gain efficiencies by filling up the queue before going and polling with PQflush. I imagine this is the exact reason that the potential for a 0 result exists. From the comment in 31.4 each call to PQputCopyData should be followed by the call to PQflush...
As is my usual I decided to use my fresh perspective to see if I could organize the material in a more structured, and in this case less repetitive, way. Sending a diff/patch and a PDF of the result of "make html"
I did not look at the 31.9.3 - Obsolete Functions section
Is there any particular rule-of-thumb for choosing "0" or "zero" that I should consider? I tended to pick "0" in almost all cases and even fixed a few otherwise untouched blocks of text.
The adjective "network" in "...to read from or write to the network connection used by libpq." seems redundant...
David J.
P.S. I am also curious as to why the documents generated using "make html" do not more closely (and there is quite a gap) match the style of the online website....
libpq_sgml_31_9_functions_associated_with_the_copy_command.diff (14K) Download Attachment libpq_sgml_31_9_functions_associated_with_the_copy_command.pdf (263K) Download AttachmentView this message in context: Re: PQputCopyEnd doesn't adhere to its API contract
Sent from the PostgreSQL - hackers mailing list archive at Nabble.com.
pgsql-hackers by date: