From 43c986a7859d0e270f630bab7a333f99e5d5da8e Mon Sep 17 00:00:00 2001
From: Aleksander Alekseev <aleksander@timescale.com>
Date: Tue, 23 May 2023 13:32:40 +0300
Subject: [PATCH v5] Clarify the "38.10.10. Shared Memory and LWLocks" section

Document the existence shmem_startup_hook, LWLockNewTrancheId() and
LWLockRegisterTranche().

Aleksander Alekseev, reviewed by Michael Paquier

Discussion: https://postgr.es/m/CAJ7c6TPKhFgL%2B54cdTD9yGpG4%2BsNcyJ%2BN1GvQqAxgWENAOa3VA%40mail.gmail.com
---
 doc/src/sgml/xfunc.sgml | 27 ++++++++++++++++++++++++---
 1 file changed, 24 insertions(+), 3 deletions(-)

diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml
index 96ba95818c..2884ca4742 100644
--- a/doc/src/sgml/xfunc.sgml
+++ b/doc/src/sgml/xfunc.sgml
@@ -3424,9 +3424,18 @@ void RequestNamedLWLockTranche(const char *tranche_name, int num_lwlocks)
      to get a pointer to this array.
     </para>
     <para>
-     An example of a <literal>shmem_request_hook</literal> can be found in
-     <filename>contrib/pg_stat_statements/pg_stat_statements.c</filename> in the
-     <productname>PostgreSQL</productname> source tree.
+     When necessary, an unique tranche ID can be allocated:
+<programlisting>
+int LWLockNewTrancheId(void)
+</programlisting>
+     Also a dynamic name in the lookup table of the current process can be assigned to the tranche:
+<programlisting>
+void LWLockRegisterTranche(int tranche_id, const char *tranche_name)
+</programlisting>
+    A complete usage example of <function>LWLockNewTrancheId</function> and
+    <function>LWLockRegisterTranche</function> can be found in
+    <filename>contrib/pg_prewarm/autoprewarm.c</filename> in the
+    <productname>PostgreSQL</productname> source tree.
     </para>
     <para>
      To avoid possible race-conditions, each backend should use the LWLock
@@ -3451,6 +3460,18 @@ if (!ptr)
 }
 </programlisting>
     </para>
+    <para>
+    It is convenient to use <literal>shmem_startup_hook</literal> which allows
+    placing all the code responsible for initializing shared memory in one place.
+    When using <literal>shmem_startup_hook</literal> the extension still needs
+    to acquire <function>AddinShmemInitLock</function> in order to work properly
+    on all the supported platforms.
+    </para>
+    <para>
+     A complete example of allocating shared memory and LWLocks can be found in
+     <filename>contrib/pg_stat_statements/pg_stat_statements.c</filename> in the
+     <productname>PostgreSQL</productname> source tree.
+    </para>
    </sect2>
 
    <sect2 id="xfunc-addin-wait-events">
-- 
2.42.0