From 65e25d4b27bbb6d0934872310c24ee19f89e9631 Mon Sep 17 00:00:00 2001
From: Masahiro Ikeda <masahiro.ikeda.us@hco.ntt.co.jp>
Date: Thu, 15 Jun 2023 13:16:00 +0900
Subject: [PATCH 3/3] Add docs to define custom wait events

---
 doc/src/sgml/monitoring.sgml |  7 +++++++
 doc/src/sgml/xfunc.sgml      | 22 +++++++++++++++++++---
 2 files changed, 26 insertions(+), 3 deletions(-)

diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml
index 5cfdc70c03..aefdc03dbd 100644
--- a/doc/src/sgml/monitoring.sgml
+++ b/doc/src/sgml/monitoring.sgml
@@ -1257,6 +1257,13 @@ postgres   27093  0.0  0.0  30096  2752 ?        Ss   11:34   0:00 postgres: ser
    </tgroup>
   </table>
 
+  <note>
+   <para>
+    Extensions can add <literal>Extension</literal> types to the list shown in
+    <xref linkend="wait-event-extension-table"/>.
+   </para>
+  </note>
+
   <table id="wait-event-io-table">
    <title>Wait Events of Type <literal>IO</literal></title>
    <tgroup cols="2">
diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml
index 9620ea9ae3..162d50e273 100644
--- a/doc/src/sgml/xfunc.sgml
+++ b/doc/src/sgml/xfunc.sgml
@@ -3397,16 +3397,16 @@ CREATE FUNCTION make_array(anyelement) RETURNS anyarray
    </sect2>
 
    <sect2 id="xfunc-shared-addin">
-    <title>Shared Memory and LWLocks</title>
+    <title>Shared Memory allocated by addins</title>
 
     <para>
-     Add-ins can reserve LWLocks and an allocation of shared memory on server
+     Add-ins can reserve LWLocks, wait events, 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</primary></indexterm>.
      The shared library should register a <literal>shmem_request_hook</literal>
      in its <function>_PG_init</function> function.  This
-     <literal>shmem_request_hook</literal> can reserve LWLocks or shared memory.
+     <literal>shmem_request_hook</literal> can reserve LWLocks, wait events, or shared memory.
      Shared memory is reserved by calling:
 <programlisting>
 void RequestAddinShmemSpace(int size)
@@ -3451,6 +3451,22 @@ if (!ptr)
 }
 </programlisting>
     </para>
+    <para>
+     wait events are reserved by calling:
+<programlisting>
+void RequestNamedExtensionWaitEventTranche(const char *tranche_name)
+</programlisting>
+     from your <literal>shmem_request_hook</literal>.  This will ensure that 
+     wait event is available under the name <literal>tranche_name</literal>,
+     which the wait event type is <literal>Extension</literal>.
+     Use <function>GetNamedExtensionWaitEventTranche</function>
+     to get a wait event information.
+    </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, same as LWLocks reservations above.
+    </para>
    </sect2>
 
    <sect2 id="extend-cpp">
-- 
2.25.1