diff options
| -rw-r--r-- | doc/src/sgml/xfunc.sgml | 30 |
1 files changed, 30 insertions, 0 deletions
diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml index 96ba95818c2..89116ae74c2 100644 --- a/doc/src/sgml/xfunc.sgml +++ b/doc/src/sgml/xfunc.sgml @@ -3429,6 +3429,29 @@ void RequestNamedLWLockTranche(const char *tranche_name, int num_lwlocks) <productname>PostgreSQL</productname> source tree. </para> <para> + There is another, more flexible method of obtaining LWLocks. First, + allocate a <literal>tranche_id</literal> from a shared counter by + calling: +<programlisting> +int LWLockNewTrancheId(void) +</programlisting> + Next, each individual process using the <literal>tranche_id</literal> + should associate it with a <literal>tranche_name</literal> by calling: +<programlisting> +void LWLockRegisterTranche(int tranche_id, const char *tranche_name) +</programlisting> + It is also required to call <function>LWLockInitialize</function> once + per LWLock, passing the <literal>tranche_id</literal> as argument: +<programlisting> +void LWLockInitialize(LWLock *lock, int tranche_id) +</programlisting> + A complete usage example of <function>LWLockNewTrancheId</function>, + <function>LWLockInitialize</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 <function>AddinShmemInitLock</function> when connecting to and initializing its allocation of shared memory, as shown here: @@ -3451,6 +3474,13 @@ 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> </sect2> <sect2 id="xfunc-addin-wait-events"> |