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

Prior to this commit the documentation showed an example of acquiring shared
memory and LWLocks from an extension without much clarification why the
extension needs to acquire AddinShmemInitLock. This can puzzle the reader
versed in *nix systems but not particularly mindful of Windows specifics.

Clarify this and also document the existence shmem_startup_hook.

Aleksander Alekseev, reviewed by TODO FIXME
Discussion: https://postgr.es/m/CAJ7c6TPKhFgL%2B54cdTD9yGpG4%2BsNcyJ%2BN1GvQqAxgWENAOa3VA%40mail.gmail.com
---
 doc/src/sgml/xfunc.sgml | 19 ++++++++++++++-----
 1 file changed, 14 insertions(+), 5 deletions(-)

diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml
index 9620ea9ae3..cf31c114bf 100644
--- a/doc/src/sgml/xfunc.sgml
+++ b/doc/src/sgml/xfunc.sgml
@@ -3423,11 +3423,6 @@ void RequestNamedLWLockTranche(const char *tranche_name, int num_lwlocks)
      <literal>tranche_name</literal>.  Use <function>GetNamedLWLockTranche</function>
      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.
-    </para>
     <para>
      To avoid possible race-conditions, each backend should use the LWLock
      <function>AddinShmemInitLock</function> when connecting to and initializing
@@ -3451,6 +3446,20 @@ 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 including Windows. This is also the reason
+    why the return value of <function>GetNamedLWLockTranche</function> is
+    conventionally stored in shared memory instead of local process memory.
+    </para>
+    <para>
+     An 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="extend-cpp">
-- 
2.40.1