postgres.git / summary / log / commit / refs

commit    ce0b0fa3e792cefc3ce325b10af224edbbf68ce7
Author:   Thomas Munro <tmunro@postgresql.org>
Date:     Tue Jul 11 20:57:55 2023 +0000
First released in: 17.0

    Doc: Adjust libpq docs about thread safety.
    
    Describe the situation now that --disable-thread-safety is gone.
    
    Author: Heikki Linnakangas <hlinnaka@iki.fi>
    Discussion: https://postgr.es/m/CA%2BhUKGLtmexrpMtxBRLCVePqV_dtWG-ZsEbyPrYc%2BNBB2TkNsw%40mail.gmail.com


doc/src/sgml/libpq.sgml | 49 +++++++++++++++++++++++-------------------------- 1 file changed, 23 insertions(+), 26 deletions(-) diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index b6f5aba1b18..a52baa27d56 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -9236,14 +9236,28 @@ void PQinitSSL(int do_ssl); </indexterm> <para> - <application>libpq</application> is reentrant and thread-safe by default. - You might need to use special compiler command-line - options when you compile your application code. Refer to your - system's documentation for information about how to build - thread-enabled applications, or look in - <filename>src/Makefile.global</filename> for <literal>PTHREAD_CFLAGS</literal> - and <literal>PTHREAD_LIBS</literal>. This function allows the querying of - <application>libpq</application>'s thread-safe status: + As of version 17, <application>libpq</application> is always reentrant and thread-safe. + However, one restriction is that no two threads attempt to manipulate + the same <structname>PGconn</structname> object at the same time. In particular, + you cannot issue concurrent commands from different threads through + the same connection object. (If you need to run concurrent commands, + use multiple connections.) + </para> + + <para> + <structname>PGresult</structname> objects are normally read-only after creation, + and so can be passed around freely between threads. However, if you use + any of the <structname>PGresult</structname>-modifying functions described in + <xref linkend="libpq-misc"/> or <xref linkend="libpq-events"/>, it's up + to you to avoid concurrent operations on the same <structname>PGresult</structname>, + too. + </para> + + <para> + In earlier versions, <application>libpq</application> could be compiled + with or without thread support, depending on compiler options. This + function allows the querying of <application>libpq</application>'s + thread-safe status: </para> <variablelist> @@ -9261,29 +9275,12 @@ int PQisthreadsafe(); <para> Returns 1 if the <application>libpq</application> is thread-safe - and 0 if it is not. + and 0 if it is not. Always returns 1 on version 17 and above. </para> </listitem> </varlistentry> </variablelist> - <para> - One thread restriction is that no two threads attempt to manipulate - the same <structname>PGconn</structname> object at the same time. In particular, - you cannot issue concurrent commands from different threads through - the same connection object. (If you need to run concurrent commands, - use multiple connections.) - </para> - - <para> - <structname>PGresult</structname> objects are normally read-only after creation, - and so can be passed around freely between threads. However, if you use - any of the <structname>PGresult</structname>-modifying functions described in - <xref linkend="libpq-misc"/> or <xref linkend="libpq-events"/>, it's up - to you to avoid concurrent operations on the same <structname>PGresult</structname>, - too. - </para> - <para> The deprecated functions <xref linkend="libpq-PQrequestCancel"/> and <xref linkend="libpq-PQoidStatus"/> are not thread-safe and should not be [parent: 68a4b58eca03]