On Thu, Sep 4, 2014 at 12:52:14PM -0400, Robert Haas wrote: > On Wed, Sep 3, 2014 at 6:24 PM, Bruce Momjian <br...@momjian.us> 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 <t...@sss.pgh.pa.us> 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 <br...@momjian.us> 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 (pgsql-hackers@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers