database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-07-30 11:03:19 +03:00
Code Activity

Add a feature for automatic initialization and finalization of dynamically

Browse Source 
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.
This commit is contained in:
Tom Lane
2006-08-08 19:15:09 +00:00
parent e00664da48
commit b09bfcaa57
12 changed files with 179 additions and 239 deletions
Download Patch File Download Diff File Expand all files Collapse all files

33
doc/src/sgml/config.sgml
View File

@ -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,38 +957,35 @@ 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.

99
doc/src/sgml/xfunc.sgml
View File

@ -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>
@ -1148,6 +1148,15 @@ CREATE FUNCTION square_root(double precision) RETURNS double precision
that fails as well, the load will fail.
</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
@ -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>
@ -1910,31 +1963,6 @@ concat_text(PG_FUNCTION_ARGS)
</para>
</listitem>
<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
@ -1945,6 +1973,13 @@ PG_MODULE_MAGIC;
</para>
</listitem>
<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