Re: PQputCopyEnd doesn't adhere to its API contract

On Wed, Sep 3, 2014 at 6:25 PM, Bruce Momjian [via PostgreSQL] <
ml-node+s1045698n5817646h50(at)n5(dot)nabble(dot)com> 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 <[hidden email]
> <http://user/SendEmail.jtp?type=node&node=5817646&i=0>> 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?
>
>
​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) <http://postgresql.1045698.n5.nabble.com/attachment/5817691/0/libpq_sgml_31_9_functions_associated_with_the_copy_command.diff>
libpq_sgml_31_9_functions_associated_with_the_copy_command.pdf (263K) <http://postgresql.1045698.n5.nabble.com/attachment/5817691/1/libpq_sgml_31_9_functions_associated_with_the_copy_command.pdf>

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