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

diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml
index 37f662da41723029fbcce27e4fa7cd0342c72d11..7ab20a6b0baa9af93d5a0e8c660ba10bd5b666a7 100644 (file)
--- a/doc/src/sgml/xfunc.sgml
+++ b/doc/src/sgml/xfunc.sgml
@@ -1,4 +1,4 @@
-
+
 
  
   User-Defined Functions
@@ -2906,6 +2906,54 @@ make_array(PG_FUNCTION_ARGS)
 CREATE FUNCTION make_array(anyelement) RETURNS anyarray
     AS 'DIRECTORY/funcs', 'make_array'
     LANGUAGE C IMMUTABLE;
+
+    
+   
+   
+    Shared Memory and LWLocks in C-Language Functions
+
+    
+     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 
+     shared-preload-libraries,
+     and the shared memory must be reserved by calling:
+
+void RequestAddinShmemSpace(int size)
+
+     from your _PG_init function.
+    
+    
+      LWLocks are reserved by calling:
+
+void RequestAddinLWLocks(int n)
+
+      from _PG_init. 
+        
+    
+      To avoid possible race-conditions, each backend should use the LWLock
+      AddinShmemInitLock when connecting to and intializing 
+      its allocation of shared memory, as shown here:
+      
+
+        static mystruct *ptr = NULL;
+
+        if (!ptr)
+        {
+                bool    found;
+
+                LWLockAcquire(AddinShmemInitLock, LW_EXCLUSIVE);
+                ptr = ShmemInitStruct("my struct name", size, &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);
+        }