Subject: Will PQregisterThreadLock() be documented?

From: Volkan YAZICI <[email-masked]>
Date: Sun, 16 Oct 2005 11:15:50 +0300

Will PQregisterThreadLock() - which is defined globally in
src/interfaces/libpq/fe-connect.c - be documented?

---

From: Bruce Momjian <[email-masked]>
Date: Sun, 16 Oct 2005 11:52:57 -0400 (EDT)

> src/interfaces/libpq/fe-connect.c - be documented?

Yes, it should be documented.

-- 
  Bruce Momjian                        |  http://candle.pha.pa.us
  [email-masked]               |  (610) 359-1001
  +  If your life is a hard drive,     |  13 Roberts Road
  +  Christ can be your backup.        |  Newtown Square, Pennsylvania 19073

---

From: Tom Lane <[email-masked]>
Date: Sun, 16 Oct 2005 12:47:44 -0400

> Yes, it should be documented.

Really?  Do we intend applications to call it?

			regards, tom lane

---

From: Bruce Momjian <[email-masked]>
Date: Sun, 16 Oct 2005 13:15:45 -0400 (EDT)

> Really?  Do we intend applications to call it?

Uh, well, we never call it ourselves, so if we don't expect other
applications to call it, why is it there?

Our code has:
	
	/*
	 *     Used to set callback that prevents concurrent access to
	 *     non-thread safe functions that libpq needs.
	 *     The default implementation uses a libpq internal mutex.
	 *     Only required for multithreaded apps that use kerberos
	 *     both within their app and for postgresql connections.
	 */
	typedef void (*pgthreadlock_t) (int acquire);
	
	extern pgthreadlock_t PQregisterThreadLock(pgthreadlock_t newhandler);

We need to research why it was added.

---

From: Tom Lane <[email-masked]>
Date: Sun, 16 Oct 2005 13:52:29 -0400

> applications to call it, why is it there?

If it's intended for apps to call, how was the patch initially accepted
with no documentation?

			regards, tom lane

---

From: Bruce Momjian <[email-masked]>
Date: Sun, 16 Oct 2005 14:21:31 -0400 (EDT)

> If it's intended for apps to call, how was the patch initially accepted

Not sure.  That's why its history needs to be researched.

---

From: Volkan YAZICI <[email-masked]>
Date: Sun, 16 Oct 2005 22:30:29 +0300

Revision 1.269: Wed Mar 24 03:44:59 2004 UTC by momjian
Branches: MAIN
] Add thread locking to SSL and Kerberos connections.
]
] I have removed the docs mentioning that SSL and Kerberos are not
] thread-safe.
]
] Manfred Spraul

Diff to previous 1.268:
http://developer.postgresql.org/cvsweb.cgi/pgsql/src/interfaces/libpq/fe-connect.c.diff?r1=1.268;r2=1.269

FYI

---

From: Tom Lane <[email-masked]>
Date: Sun, 16 Oct 2005 18:10:38 -0400

> ] I have removed the docs mentioning that SSL and Kerberos are not

I note that PQinitSSL is likewise documentation-free.

Also, neither one of these two routines is listed in exports.txt,
meaning that Windows users are physically unable to call them
even if they knew they existed :-(

			regards, tom lane

---

From: Bruce Momjian <[email-masked]>
Date: Mon, 24 Oct 2005 11:38:17 -0400 (EDT)

> even if they knew they existed :-(

I have applied the following patch to document PQinitSSL() and
PQregisterThreadLock().

I also remove the crypt() mention in the libpq threading section and
added a single sentence in the client-auth manual page under crypt(). 
Crypt authentication is so old now that a separate paragraph about it
seemed unwise.

I also added a comment about our use of locking around pqGetpwuid().

-- 
  Bruce Momjian                        |  http://candle.pha.pa.us
  [email-masked]               |  (610) 359-1001
  +  If your life is a hard drive,     |  13 Roberts Road
  +  Christ can be your backup.        |  Newtown Square, Pennsylvania 19073
Index: doc/src/sgml/client-auth.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/client-auth.sgml,v
retrieving revision 1.83
diff -c -c -r1.83 client-auth.sgml
*** doc/src/sgml/client-auth.sgml	14 Aug 2005 23:35:37 -0000	1.83
--- doc/src/sgml/client-auth.sgml	24 Oct 2005 15:30:13 -0000
***************
*** 337,342 ****
--- 337,343 ----
            authentication.
            Since the password is sent in clear text over the
            network, this should not be used on untrusted networks.
+           It also does not usually work with threaded client applications.
            See <xref linkend="auth-password"> for details.
           </para>
          </listitem>
Index: doc/src/sgml/libpq.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v
retrieving revision 1.196
diff -c -c -r1.196 libpq.sgml
*** doc/src/sgml/libpq.sgml	20 Oct 2005 23:57:51 -0000	1.196
--- doc/src/sgml/libpq.sgml	24 Oct 2005 15:30:15 -0000
***************
*** 4032,4037 ****
--- 4032,4046 ----
     fail if the server does not present a certificate; therefore, to
     use this feature the server must also have a <filename>root.crt</> file.
    </para>
+ 
+   <para>
+    If you are using <acronym>SSL</> inside your application (in addition to
+    inside <application>libpq</application>), you can use <function>PQinitSSL(int)</>
+    to tell <application>libpq</application> that the <acronym>SSL</> library
+    has already been initialized by your application.
+   </para>
+ 
+ 
  </sect1>

***************
*** 4081,4092 ****
  </para>
  
  <para>
! <application>libpq</application> applications that use the
! <literal>crypt</literal> authentication method rely on the
! <literal>crypt()</literal> operating system function, which is often
! not thread-safe.<indexterm><primary>crypt</><secondary>thread
! safety</></> It is better to use the <literal>md5</literal> method,
! which is thread-safe on all platforms.
  </para>
  
  <para>
--- 4090,4101 ----
  </para>
  
  <para>
! If you are using Kerberos inside your application (in addition to inside 
! <application>libpq</application>), you will need to do locking around 
! Kerberos calls because Kerberos functions are not thread-safe.  See 
! function <function>PQregisterThreadLock</> in the 
! <application>libpq</application> source code for a way to do cooperative 
! locking between <application>libpq</application> and your application.
  </para>
  
  <para>
Index: src/interfaces/libpq/fe-auth.c
===================================================================
RCS file: /cvsroot/pgsql/src/interfaces/libpq/fe-auth.c,v
retrieving revision 1.106
diff -c -c -r1.106 fe-auth.c
*** src/interfaces/libpq/fe-auth.c	17 Oct 2005 16:24:20 -0000	1.106
--- src/interfaces/libpq/fe-auth.c	24 Oct 2005 15:30:16 -0000
***************
*** 500,505 ****
--- 500,515 ----
  	struct passwd *pw = NULL;
  #endif
  
+ 	/*
+ 	 *	pglock_thread() really only needs to be called around
+ 	 *	pg_krb5_authname(), but some users are using configure
+ 	 *	--enable-thread-safety-force, so we might as well do
+ 	 *	the locking within our library to protect pqGetpwuid().
+ 	 *	In fact, application developers can use getpwuid()
+ 	 *	in their application if they use the locking call we
+ 	 *	provide, or install their own locking function using
+ 	 *	PQregisterThreadLock().
+ 	 */
  	pglock_thread();
  
  #ifdef KRB5
Index: src/interfaces/libpq/fe-secure.c
===================================================================
RCS file: /cvsroot/pgsql/src/interfaces/libpq/fe-secure.c,v
retrieving revision 1.72
diff -c -c -r1.72 fe-secure.c
*** src/interfaces/libpq/fe-secure.c	15 Oct 2005 02:49:48 -0000	1.72
--- src/interfaces/libpq/fe-secure.c	24 Oct 2005 15:30:17 -0000
***************
*** 220,227 ****

  /*
!  * Exported (but as yet undocumented) function to allow application to
!  * tell us it's already initialized OpenSSL.
   */
  void
  PQinitSSL(int do_init)
--- 220,227 ----

  /*
!  *	Exported function to allow application to tell us it's already
!  *	initialized OpenSSL.
   */
  void
  PQinitSSL(int do_init)