Re: PQputCopyEnd doesn't adhere to its API contract

On Thu, Sep 4, 2014 at 1:00 PM, Robert Haas [via PostgreSQL] <
ml-node+s1045698n5817809h3(at)n5(dot)nabble(dot)com> wrote:

> On Thu, Sep 4, 2014 at 12:53 PM, Bruce Momjian <[hidden email]
> <http://user/SendEmail.jtp?type=node&node=5817809&i=0>> wrote:
>
> > On Thu, Sep 4, 2014 at 12:52:14PM -0400, Robert Haas wrote:
> >> On Wed, Sep 3, 2014 at 6:24 PM, Bruce Momjian <[hidden email]
> <http://user/SendEmail.jtp?type=node&node=5817809&i=1>> 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=5817809&i=2>> 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.
> >
> > OK, did David G Johnston email comments from today help here?
>
> I didn't look at them in detail, but they don't seem to match the
> style of our documentation generally.
>
>
​Specific observations would help though that is partly the idea - I've
been more focused on clarity and organization even if it requires deviating
from the current general documentation style.​

​If this is not acceptable I'm happy to incorporate the ideas of others to
try and get the best of both worlds.

David J.
​

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