Flesh out the background worker documentation.

Make it more clear that bgw_main is usually not what you want.  Put the
background worker flags in a variablelist rather than having them as
part of a paragraph.  Explain important limits on how bgw_main_arg can
be used.

Craig Ringer, substantially revised by me.

diff --git a/doc/src/sgml/bgworker.sgml b/doc/src/sgml/bgworker.sgml
index ef28f7251141603a9158985cb304c8b206c584e6..c17d39857c2e870264abc00a64753ce63a2f1f08 100644 (file)
--- a/doc/src/sgml/bgworker.sgml
+++ b/doc/src/sgml/bgworker.sgml
@@ -70,14 +70,39 @@ typedef struct BackgroundWorker
 
   
    bgw_flags is a bitwise-or'd bit mask indicating the
-   capabilities that the module wants.  Possible values are
-   BGWORKER_SHMEM_ACCESS (requesting shared memory access)
-   and BGWORKER_BACKEND_DATABASE_CONNECTION (requesting the
-   ability to establish a database connection, through which it can later run
-   transactions and queries). A background worker using
-   BGWORKER_BACKEND_DATABASE_CONNECTION to connect to
-   a database must also attach shared memory using
-   BGWORKER_SHMEM_ACCESS, or worker start-up will fail.
+   capabilities that the module wants.  Possible values are:
+   
+
+    
+     BGWORKER_SHMEM_ACCESS
+     
+      
+       BGWORKER_SHMEM_ACCESS
+       Requests shared memory access.  Workers without shared memory access
+       cannot access any of PostgreSQL's shared
+       data structures, such as heavyweight or lightweight locks, shared
+       buffers, or any custom data structures which the worker itself may
+       wish to create and use.
+      
+     
+    
+
+    
+     BGWORKER_BACKEND_DATABASE_CONNECTION
+     
+      
+       BGWORKER_BACKEND_DATABASE_CONNECTION
+       Requests the ability to establish a database connection through which it
+       can later run transactions and queries.  A background worker using
+       BGWORKER_BACKEND_DATABASE_CONNECTION to connect to a
+       database must also attach shared memory using
+       BGWORKER_SHMEM_ACCESS, or worker start-up will fail.
+      
+     
+    
+
+   
+
   
 
   
@@ -106,34 +131,55 @@ typedef struct BackgroundWorker
 
   
    bgw_main is a pointer to the function to run when
-   the process is started.  This function must take a single argument of type
-   Datum and return void.
-   bgw_main_arg will be passed to it as its only
-   argument.  Note that the global variable MyBgworkerEntry
-   points to a copy of the BackgroundWorker structure
-   passed at registration time. bgw_main may be
-   NULL; in that case, bgw_library_name and
-   bgw_function_name will be used to determine
-   the entry point.  This is useful for background workers launched after
-   postmaster startup, where the postmaster does not have the requisite
-   library loaded.
+   the process is started.  This field can only safely be used to launch
+   functions within the core server, because shared libraries may be loaded
+   at different starting addresses in different backend processes.  This will
+   happen on all platforms when the library is loaded using any mechanism
+   other than .  Even when that
+   mechanism is used, address space layout variations will still occur on
+   Windows, and when EXEC_BACKEND is used.  Therefore, most users
+   of this API should set this field to NULL.  If it is non-NULL, it takes
+   precedence over bgw_library_name and
+   bgw_function_name.
   
 
   
    bgw_library_name is the name of a library in
    which the initial entry point for the background worker should be sought.
-   It is ignored unless bgw_main is NULL.
-   But if bgw_main is NULL, then the named library
-   will be dynamically loaded by the worker process and
-   bgw_function_name will be used to identify
-   the function to be called.
+   The named library will be dynamically loaded by the worker process and
+   bgw_function_name will be used to identify the
+   function to be called.  If loading a function from the core code,
+   bgw_main should be set instead.
   
 
   
    bgw_function_name is the name of a function in
    a dynamically loaded library which should be used as the initial entry point
-   for a new background worker.  It is ignored unless
-   bgw_main is NULL.
+   for a new background worker.
+  
+
+  
+   bgw_main_arg is the Datum argument
+   to the background worker main function.  Regardless of whether that
+   function is specified via bgw_main or via the combination
+   of bgw_library_name and bgw_function_name,
+   this main function should take a single argument of type Datum
+   and return void.  bgw_main_arg will be
+   passed as the argument.  In addition, the global variable
+   MyBgworkerEntry
+   points to a copy of the BackgroundWorker structure
+   passed at registration time; the worker may find it helpful to examine
+   this structure.
+  
+
+  
+   On Windows (and anywhere else where EXEC_BACKEND is
+   defined) or in dynamic background workers it is not safe to pass a
+   Datum by reference, only by value. If an argument is required, it
+   is safest to pass an int32 or other small value and use that as an index
+   into an array allocated in shared memory. If a value like a cstring
+   or text is passed then the pointer won't be valid from the
+   new background worker process.