Shared Memory Hooks Documentation (was Re: [PATCHES] New shared memory hooks proposal)

[Marc Munro]

On Sun, 2006-10-15 at 16:36 -0400, Tom Lane wrote:

> I'm not entirely sure where to put it, either.  Subsection 32.9.1 (Dynamic
> Loading) is pretty basic stuff for first-time C-function authors ---
> this seems off-topic for that section.  Maybe a new subsection down near
> the end of 32.9?  Another possibility is somewhere in the Internals
> chapters, although I don't offhand see an obvious place there either.
> 
> 
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.

I have, btw, verified that this works in the forthcoming release of
Veil.

__
Marc


*** xfunc.sgml	2006-10-31 12:52:01.000000000 -0800
--- xfunc.sgml.new	2006-10-31 12:51:51.000000000 -0800
***************
*** 2909,2912 ****
--- 2909,2960 ----
  </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>
    </sect1>

signature.asc
Description: This is a digitally signed message part