On Thu, Sep 4, 2014 at 12:52:14PM -0400, Robert Haas wrote:
> On Wed, Sep 3, 2014 at 6:24 PM, Bruce Momjian <[email protected]> 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 <[email protected]> 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.
I have developed such a patch --- attached. I didn't see any other
mentions of blocking in the docs.
--
Bruce Momjian <[email protected]> http://momjian.us
EnterpriseDB http://enterprisedb.com
+ Everyone has their own god. +
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
new file mode 100644
index de272c5..ad104a3
*** a/doc/src/sgml/libpq.sgml
--- b/doc/src/sgml/libpq.sgml
*************** int PQsetnonblocking(PGconn *conn, int a
*** 4318,4325 ****
<para>
In the nonblocking state, calls to
<function>PQsendQuery</function>, <function>PQputline</function>,
! <function>PQputnbytes</function>, and
! <function>PQendcopy</function> will not block but instead return
an error if they need to be called again.
</para>
--- 4318,4325 ----
<para>
In the nonblocking state, calls to
<function>PQsendQuery</function>, <function>PQputline</function>,
! <function>PQputnbytes</function>, <function>PQputCopyData</function>,
! and <function>PQendcopy</function> will not block but instead return
an error if they need to be called again.
</para>
*************** int PQputCopyData(PGconn *conn,
*** 4961,4969 ****
<para>
Transmits the <command>COPY</command> data in the specified
<parameter>buffer</>, of length <parameter>nbytes</>, to the server.
! The result is 1 if the data was sent, zero if it was not sent
! because the attempt would block (this case is only possible if the
! connection is in nonblocking mode), or -1 if an error occurred.
(Use <function>PQerrorMessage</function> to retrieve details if
the return value is -1. If the value is zero, wait for write-ready
and try again.)
--- 4961,4969 ----
<para>
Transmits the <command>COPY</command> data in the specified
<parameter>buffer</>, of length <parameter>nbytes</>, to the server.
! The result is 1 if the data was queued, zero if it was not queued
! because of full buffers (this will only happen in nonblocking mode),
! or -1 if an error occurred.
(Use <function>PQerrorMessage</function> to retrieve details if
the return value is -1. If the value is zero, wait for write-ready
and try again.)
*************** int PQputCopyEnd(PGconn *conn,
*** 5009,5021 ****
connections.)
</para>
! <para>
! The result is 1 if the termination data was sent, zero if it was
! not sent because the attempt would block (this case is only possible
! if the connection is in nonblocking mode), or -1 if an error
! occurred. (Use <function>PQerrorMessage</function> to retrieve
! details if the return value is -1. If the value is zero, wait for
! write-ready and try again.)
</para>
<para>
--- 5009,5026 ----
connections.)
</para>
! <para>
! 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 <function>PQputCopyEnd</> call
! again.) If a hard error occurs, -1 is returned; you can use
! <function>PQerrorMessage</function> to retrieve details.
</para>
<para>
--
Sent via pgsql-hackers mailing list ([email protected])
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers
