doc: Expand section related to LWLocks and shared memory

The documentation includes a section describing how to define custom
LWLocks in extensions using the shmem hooks.  However, it has never
mentioned the second, more flexible method based on the following
routines:
- LWLockNewTrancheId() to allocate a tranche ID.
- LWLockRegisterTranche() to associate a name to a tranche ID.
- LWLockInitialize() to initialize a LWLock with a tranche ID.

autoprewarm.c is the only example of extension in the tree that
allocates a LWLock this way.

This commit adds some documentation about all that.  While on it, a
comment is added about the need of AddinShmemInitLock.  This is required
especially for EXEC_BACKEND builds (aka Windows, normally), as per a
remark from Alexander, because backends can execute shmem initialization
paths concurrently.

Author: Aleksander Alekseev, Michael Paquier
Discussion: https://postgr.es/m/CAJ7c6TPKhFgL+54cdTD9yGpG4+sNcyJ+N1GvQqAxgWENAOa3VA@mail.gmail.com

diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml
index 96ba95818c2d5e568e0f9906b0ea132a198cee68..89116ae74c2b9bf8194f2b82b1eddf43012e8c41 100644 (file)
--- a/doc/src/sgml/xfunc.sgml
+++ b/doc/src/sgml/xfunc.sgml
@@ -3428,6 +3428,29 @@ void RequestNamedLWLockTranche(const char *tranche_name, int num_lwlocks)
      contrib/pg_stat_statements/pg_stat_statements.c in the
      PostgreSQL source tree.
     
+    
+     There is another, more flexible method of obtaining LWLocks. First,
+     allocate a tranche_id from a shared counter by
+     calling:
+
+int LWLockNewTrancheId(void)
+
+     Next, each individual process using the tranche_id
+     should associate it with a tranche_name by calling:
+
+void LWLockRegisterTranche(int tranche_id, const char *tranche_name)
+
+     It is also required to call LWLockInitialize once
+     per LWLock, passing the tranche_id as argument:
+
+void LWLockInitialize(LWLock *lock, int tranche_id)
+
+     A complete usage example of LWLockNewTrancheId,
+     LWLockInitialize and
+     LWLockRegisterTranche can be found in
+     contrib/pg_prewarm/autoprewarm.c in the
+     PostgreSQL source tree.
+    
     
      To avoid possible race-conditions, each backend should use the LWLock
      AddinShmemInitLock when connecting to and initializing
@@ -3451,6 +3474,13 @@ if (!ptr)
 }
 
     
+    
+     It is convenient to use shmem_startup_hook which allows
+     placing all the code responsible for initializing shared memory in one
+     place. When using shmem_startup_hook the extension
+     still needs to acquire AddinShmemInitLock in order to
+     work properly on all the supported platforms.
+