From 02f9ac6e654a3c2d709c460bb4e7cf17fab83d81 Mon Sep 17 00:00:00 2001
From: Bruce Momjian <bruce@momjian.us>
Date: Thu, 23 Nov 2006 03:52:05 +0000
Subject: [PATCH] Shared Memory Hooks Documentation

This patch, against xfunc.sgml, adds a new subsection 33.9.12, Shared
Memory and LWLocks in C-Language Functions, describing how shared memory
and lwlocks may be requested by C add-in functions.

Marc Munro
---
 doc/src/sgml/xfunc.sgml | 48 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml
index ce1fbee11e..3e338ab511 100644
--- a/doc/src/sgml/xfunc.sgml
+++ b/doc/src/sgml/xfunc.sgml
@@ -2906,6 +2906,54 @@ make_array(PG_FUNCTION_ARGS)
 CREATE FUNCTION make_array(anyelement) RETURNS anyarray
     AS '<replaceable>DIRECTORY</replaceable>/funcs', 'make_array'
     LANGUAGE C IMMUTABLE;
+</programlisting>
+    </para>
+   </sect2>
+   <sect2>
+    <title>Shared Memory and LWLocks in C-Language Functions</title>
+
+    <para>
+     Add-ins may reserve LWLocks and an allocation of shared memory on server
+     startup.  The add-in's shared library must be preloaded, by specifying
+     it in 
+     <xref linkend="guc-shared-preload-libraries"><indexterm><primary>shared-preload-libraries</></>,
+     and the shared memory must be reserved by calling:
+<programlisting>
+void RequestAddinShmemSpace(int size)
+</programlisting>
+     from your <literal>_PG_init</> function.
+    </para>
+    <para>
+      LWLocks are reserved by calling:
+<programlisting>
+void RequestAddinLWLocks(int n)
+</programlisting>
+      from <literal>_PG_init</>. 
+    </para>	
+    <para>
+      To avoid possible race-conditions, each backend should use the LWLock
+      <literal>AddinShmemInitLock</> when connecting to and intializing 
+      its allocation of shared memory, as shown here:
+      
+<programlisting>
+        static mystruct *ptr = NULL;
+
+        if (!ptr)
+        {
+                bool    found;
+
+                LWLockAcquire(AddinShmemInitLock, LW_EXCLUSIVE);
+                ptr = ShmemInitStruct("my struct name", size, &amp;found);
+                if (!ptr)
+                        elog(ERROR, "out of shared memory");
+                if (!found)
+                {
+                        initialize contents of shmem area;
+                        acquire any requested LWLocks using:
+                        ptr->mylockid = LWLockAssign();
+                }
+                LWLockRelease(AddinShmemInitLock);
+        }
 </programlisting>
     </para>
    </sect2>
-- 
2.39.5