From b09bfcaa576c1a3e0c34a747a502bae909b984a8 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Tue, 8 Aug 2006 19:15:09 +0000 Subject: 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. --- doc/src/sgml/config.sgml | 33 ++++++++-------- doc/src/sgml/xfunc.sgml | 99 ++++++++++++++++++++++++++++++++---------------- 2 files changed, 82 insertions(+), 50 deletions(-) (limited to 'doc/src') 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 @@ - + Server Configuration @@ -957,38 +957,35 @@ SET ENABLE_SEQSCAN TO OFF; 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 - '$libdir/mylib:mylib_init' would cause - mylib to be preloaded and mylib_init - to be executed. If more than one library is to be loaded, - separate their names with commas. - - - - 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, + '$libdir/mylib' would cause + mylib.so (or on some platforms, + mylib.sl) to be preloaded from the installation's + standard library directory. PostgreSQL procedural language libraries can be preloaded in this way, typically by using the - syntax '$libdir/plXXX:plXXX_init' where + syntax '$libdir/plXXX' where XXX is pgsql, perl, tcl, or python. - 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. + + If a specified library is not found, + the server will fail to start. + + Every PostgreSQL-supported library has a magic block that is checked to guarantee compatibility. 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 @@ - + User-Defined Functions @@ -1148,6 +1148,15 @@ CREATE FUNCTION square_root(double precision) RETURNS double precision that fails as well, the load will fail. + + It is recommended to locate shared libraries either relative to + $libdir or through the dynamic library path. + This simplifies version upgrades if the new installation is at a + different location. The actual directory that + $libdir stands for can be found out with the + command pg_config --pkglibdir. + + The user ID the PostgreSQL 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 + + magic block + + + + To ensure that a dynamically loaded object file is not loaded into an + incompatible server, PostgreSQL checks that the + file contains a magic block with the appropriate contents. + This allows the server to detect obvious incompatibilities, such as code + compiled for a different major version of + PostgreSQL. A magic block is required as of + PostgreSQL 8.2. To include a magic block, + write this in one (and only one) of the module source files, after having + included the header fmgr.h: + + +#ifdef PG_MODULE_MAGIC +PG_MODULE_MAGIC; +#endif + + + The #ifdef test can be omitted if the code doesn't + need to compile against pre-8.2 PostgreSQL + releases. + + 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. + + _PG_init + + + _PG_fini + + + library initialization function + + + library finalization function + + - It is recommended to locate shared libraries either relative to - $libdir or through the dynamic library path. - This simplifies version upgrades if the new installation is at a - different location. The actual directory that - $libdir stands for can be found out with the - command pg_config --pkglibdir. + Optionally, a dynamically loaded file can contain initialization and + finalization functions. If the file includes a function named + _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 + _PG_fini, that function will be called immediately before + unloading the file. Likewise, the function receives no parameters and + should return void. Note that _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 LOAD command.) @@ -1910,31 +1963,6 @@ concat_text(PG_FUNCTION_ARGS) - - - To ensure your module is not loaded into an incompatible server, - it must include a magic block. This allows - the server to detect obvious incompatibilities, such as a module - compiled for a different major version of - PostgreSQL. A magic block is required - as of PostgreSQL 8.2. To include a magic - block, write this in one (and only one) of your module source files, - after having included the header fmgr.h: - - - -#ifdef PG_MODULE_MAGIC -PG_MODULE_MAGIC; -#endif - - - - The #ifdef test can be omitted if your code doesn't - need to compile against pre-8.2 PostgreSQL - releases. - - - Compiling and linking your code so that it can be dynamically @@ -1945,6 +1973,13 @@ PG_MODULE_MAGIC; + + + Remember to define a magic block for your shared library, + as described in . + + + When allocating memory, use the -- cgit v1.2.3