Add a feature for automatic initialization and finalization of dynamically

loaded libraries: call functions _PG_init() and _PG_fini() if the library
defines such symbols.  Hence we no longer need to specify an initialization
function in preload_libraries: we can assume that the library used the
_PG_init() convention, instead.  This removes one source of pilot error
in use of preloaded libraries.  Original patch by Ralf Engelschall,
preload_libraries changes by me.

2 files changed, 82 insertions, 50 deletions

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index c1c42656ad7..706ccba56c8 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/config.sgml,v 1.72 2006/08/08 01:23:15 momjian Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/config.sgml,v 1.73 2006/08/08 19:15:07 tgl Exp $ -->
 
 <chapter Id="runtime-config">
   <title>Server Configuration</title>
@@ -957,39 +957,36 @@ SET ENABLE_SEQSCAN TO OFF;
       <listitem>
        <para>
         This variable specifies one or more shared libraries that are
-        to be preloaded at server start. A parameterless
-        initialization function can optionally be called for each
-        library.  To specify that, add a colon and the name of the
-        initialization function after the library name. For example
-        <literal>'$libdir/mylib:mylib_init'</literal> would cause
-        <literal>mylib</> to be preloaded and <literal>mylib_init</>
-        to be executed. If more than one library is to be loaded,
-        separate their names with commas.
-       </para>
-
-       <para>
-        If a specified library or initialization function is not found,
-        the server will fail to start.
+        to be preloaded at server start. If more than one library is to be
+        loaded, separate their names with commas. For example,
+        <literal>'$libdir/mylib'</literal> would cause
+        <literal>mylib.so</> (or on some platforms,
+        <literal>mylib.sl</>) to be preloaded from the installation's
+        standard library directory.
        </para>
 
        <para>
         <productname>PostgreSQL</productname> procedural language
         libraries can be preloaded in this way, typically by using the
-        syntax <literal>'$libdir/plXXX:plXXX_init'</literal> where
+        syntax <literal>'$libdir/plXXX'</literal> where
         <literal>XXX</literal> is <literal>pgsql</>, <literal>perl</>,
         <literal>tcl</>, or <literal>python</>.
        </para>
 
        <para>
-        By preloading a shared library (and initializing it if
-        applicable), the library startup time is avoided when the
-        library is first used.  However, the time to start each new
+        By preloading a shared library, the library startup time is avoided
+        when the library is first used.  However, the time to start each new
         server process may increase slightly, even if that process never
         uses the library.  So this parameter is recommended only for
         libraries that will be used in most sessions. 
        </para>
 
        <para>
+        If a specified library is not found,
+        the server will fail to start.
+       </para>
+
+       <para>
         Every  PostgreSQL-supported library has a <quote>magic
         block</> that is checked to guarantee compatibility.  
         For this reason, non-PostgreSQL libraries cannot be 
diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml
index 6321bf5b0a7..ae6604f7a27 100644
--- a/doc/src/sgml/xfunc.sgml
+++ b/doc/src/sgml/xfunc.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/xfunc.sgml,v 1.115 2006/05/31 20:58:09 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/xfunc.sgml,v 1.116 2006/08/08 19:15:07 tgl Exp $ -->
 
  <sect1 id="xfunc">
   <title>User-Defined Functions</title>
@@ -1149,6 +1149,15 @@ CREATE FUNCTION square_root(double precision) RETURNS double precision
    </para>
 
    <para>
+    It is recommended to locate shared libraries either relative to
+    <literal>$libdir</literal> or through the dynamic library path.
+    This simplifies version upgrades if the new installation is at a
+    different location.  The actual directory that
+    <literal>$libdir</literal> stands for can be found out with the
+    command <literal>pg_config --pkglibdir</literal>.
+   </para>
+
+   <para>
     The user ID the <productname>PostgreSQL</productname> server runs
     as must be able to traverse the path to the file you intend to
     load.  Making the file or a higher-level directory not readable
@@ -1173,6 +1182,32 @@ CREATE FUNCTION square_root(double precision) RETURNS double precision
     </para>
    </note>
 
+   <indexterm zone="xfunc-c-dynload">
+    <primary>magic block</primary>
+   </indexterm>
+
+   <para>
+    To ensure that a dynamically loaded object file is not loaded into an
+    incompatible server, <productname>PostgreSQL</productname> checks that the
+    file contains a <quote>magic block</> with the appropriate contents.
+    This allows the server to detect obvious incompatibilities, such as code
+    compiled for a different major version of
+    <productname>PostgreSQL</productname>.  A magic block is required as of
+    <productname>PostgreSQL</productname> 8.2.  To include a magic block,
+    write this in one (and only one) of the module source files, after having
+    included the header <filename>fmgr.h</>:
+
+<programlisting>
+#ifdef PG_MODULE_MAGIC
+PG_MODULE_MAGIC;
+#endif
+</programlisting>
+
+    The <literal>#ifdef</> test can be omitted if the code doesn't
+    need to compile against pre-8.2 <productname>PostgreSQL</productname>
+    releases.
+   </para>
+
    <para>
     After it is used for the first time, a dynamically loaded object
     file is retained in memory.  Future calls in the same session to
@@ -1183,13 +1218,31 @@ CREATE FUNCTION square_root(double precision) RETURNS double precision
     fresh session.
    </para>
 
+   <indexterm zone="xfunc-c-dynload">
+    <primary>_PG_init</primary>
+   </indexterm>
+   <indexterm zone="xfunc-c-dynload">
+    <primary>_PG_fini</primary>
+   </indexterm>
+   <indexterm zone="xfunc-c-dynload">
+    <primary>library initialization function</primary>
+   </indexterm>
+   <indexterm zone="xfunc-c-dynload">
+    <primary>library finalization function</primary>
+   </indexterm>
+
    <para>
-    It is recommended to locate shared libraries either relative to
-    <literal>$libdir</literal> or through the dynamic library path.
-    This simplifies version upgrades if the new installation is at a
-    different location.  The actual directory that
-    <literal>$libdir</literal> stands for can be found out with the
-    command <literal>pg_config --pkglibdir</literal>.
+    Optionally, a dynamically loaded file can contain initialization and
+    finalization functions.  If the file includes a function named
+    <literal>_PG_init</>, that function will be called immediately after
+    loading the file.  The function receives no parameters and should
+    return void.  If the file includes a function named
+    <literal>_PG_fini</>, that function will be called immediately before
+    unloading the file.  Likewise, the function receives no parameters and
+    should return void.  Note that <literal>_PG_fini</> will only be called
+    during an unload of the file, not during process termination.
+    (Presently, an unload only happens in the context of re-loading
+    the file due to an explicit <command>LOAD</> command.)
    </para>
 
   </sect2>
@@ -1912,31 +1965,6 @@ concat_text(PG_FUNCTION_ARGS)
 
       <listitem>
        <para>
-        To ensure your module is not loaded into an incompatible server,
-        it must include a <quote>magic block</>.  This allows
-        the server to detect obvious incompatibilities, such as a module
-        compiled for a different major version of
-        <productname>PostgreSQL</productname>.  A magic block is required
-        as of <productname>PostgreSQL</productname> 8.2.  To include a magic
-        block, write this in one (and only one) of your module source files,
-        after having included the header <filename>fmgr.h</>:
-       </para>
-
-<programlisting>
-#ifdef PG_MODULE_MAGIC
-PG_MODULE_MAGIC;
-#endif
-</programlisting>
-
-       <para>
-        The <literal>#ifdef</> test can be omitted if your code doesn't
-        need to compile against pre-8.2 <productname>PostgreSQL</productname>
-        releases.
-       </para>
-      </listitem>
-
-      <listitem>
-       <para>
         Compiling and linking your code so that it can be dynamically
         loaded into <productname>PostgreSQL</productname> always
         requires special flags.  See <xref linkend="dfunc"> for a
@@ -1947,6 +1975,13 @@ PG_MODULE_MAGIC;
 
       <listitem>
        <para>
+        Remember to define a <quote>magic block</> for your shared library,
+        as described in <xref linkend="xfunc-c-dynload">.
+       </para>
+      </listitem>
+
+      <listitem>
+       <para>
         When allocating memory, use the
         <productname>PostgreSQL</productname> functions
         <function>palloc</function><indexterm><primary>palloc</></> and <function>pfree</function><indexterm><primary>pfree</></>