diff --git a/doc/src/sgml/bgworker.sgml b/doc/src/sgml/bgworker.sgml index ef28f72511..c17d39857c 100644 --- 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.