diff options
Diffstat (limited to 'doc/src')
| -rw-r--r-- | doc/src/sgml/installation.sgml | 30 | ||||
| -rw-r--r-- | doc/src/sgml/xfunc.sgml | 69 |
2 files changed, 99 insertions, 0 deletions
diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml index bb55695300c..e73902b3f8f 100644 --- a/doc/src/sgml/installation.sgml +++ b/doc/src/sgml/installation.sgml @@ -1656,6 +1656,21 @@ build-postgresql: </listitem> </varlistentry> + <varlistentry id="configure-option-enable-injection-points"> + <term><option>--enable-injection-points</option></term> + <listitem> + <para> + Compiles <productname>PostgreSQL</productname> with support for + injection points in the server. Injection points allow to run + user-defined code from within the server in pre-defined code paths. + This helps in testing and in the investigation of concurrency scenarios + in a controlled fashion. This option is disabled by default. See + <xref linkend="xfunc-addin-injection-points"/> for more details. This + option is intended to be used only by developers for testing. + </para> + </listitem> + </varlistentry> + <varlistentry id="configure-option-with-segsize-blocks"> <term><option>--with-segsize-blocks=SEGSIZE_BLOCKS</option></term> <listitem> @@ -3160,6 +3175,21 @@ ninja install </listitem> </varlistentry> + <varlistentry id="configure-injection-points-meson"> + <term><option>-Dinjection_points={ true | false }</option></term> + <listitem> + <para> + Compiles <productname>PostgreSQL</productname> with support for + injection points in the server. Injection points allow to run + user-defined code from within the server in pre-defined code paths. + This helps in testing and in the investigation of concurrency scenarios + in a controlled fashion. This option is disabled by default. See + <xref linkend="xfunc-addin-injection-points"/> for more details. This + option is intended to be used only by developers for testing. + </para> + </listitem> + </varlistentry> + <varlistentry id="configure-segsize-blocks-meson"> <term><option>-Dsegsize_blocks=SEGSIZE_BLOCKS</option></term> <listitem> diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml index 0ad9f38e902..8a79ad0943f 100644 --- a/doc/src/sgml/xfunc.sgml +++ b/doc/src/sgml/xfunc.sgml @@ -3599,6 +3599,75 @@ uint32 WaitEventExtensionNew(const char *wait_event_name) </para> </sect2> + <sect2 id="xfunc-addin-injection-points"> + <title>Injection Points</title> + + <para> + An injection point with a given <literal>name</literal> is declared using + macro: +<programlisting> +INJECTION_POINT(name); +</programlisting> + + There are a few injection points already declared at strategic points + within the server code. After adding a new injection point the code needs + to be compiled in order for that injection point to be available in the + binary. Add-ins written in C-language can declare injection points in + their own code using the same macro. + </para> + + <para> + Add-ins can attach callbacks to an already-declared injection point by + calling: +<programlisting> +extern void InjectionPointAttach(const char *name, + const char *library, + const char *function); +</programlisting> + + <literal>name</literal> is the name of the injection point, which when + reached during execution will execute the <literal>function</literal> + loaded from <literal>library</literal>. + </para> + + <para> + Here is an example of callback for + <literal>InjectionPointCallback</literal>: +<programlisting> +static void +custom_injection_callback(const char *name) +{ + elog(NOTICE, "%s: executed custom callback", name); +} +</programlisting> + This callback prints a message to server error log with severity + <literal>NOTICE</literal>, but callbacks may implement more complex + logic. + </para> + + <para> + Optionally, it is possible to detach an injection point by calling: +<programlisting> +extern void InjectionPointDetach(const char *name); +</programlisting> + </para> + + <para> + A callback attached to an injection point is available across all the + backends including the backends started after + <literal>InjectionPointAttach</literal> is called. It remains attached + while the server is running or until the injection point is detached + using <literal>InjectionPointDetach</literal>. + </para> + + <para> + Enabling injections points requires + <option>--enable-injection-points</option> with + <command>configure</command> or <option>-Dinjection_points=true</option> + with <application>Meson</application>. + </para> + </sect2> + <sect2 id="extend-cpp"> <title>Using C++ for Extensibility</title> |