src/include/postmaster/bgworker.h

   1 /*--------------------------------------------------------------------
   2  * bgworker.h
   3  *              POSTGRES pluggable background workers interface
   4  *
   5  * A background worker is a process able to run arbitrary, user-supplied code,
   6  * including normal transactions.
   7  *
   8  * Any external module loaded via shared_preload_libraries can register a
   9  * worker.  Workers can also be registered dynamically at runtime.  In either
  10  * case, the worker process is forked from the postmaster and runs the
  11  * user-supplied "main" function.  This code may connect to a database and
  12  * run transactions.  Workers can remain active indefinitely, but will be
  13  * terminated if a shutdown or crash occurs.
  14  *
  15  * If the fork() call fails in the postmaster, it will try again later.  Note
  16  * that the failure can only be transient (fork failure due to high load,
  17  * memory pressure, too many processes, etc); more permanent problems, like
  18  * failure to connect to a database, are detected later in the worker and dealt
  19  * with just by having the worker exit normally. A worker which exits with
  20  * a return code of 0 will never be restarted and will be removed from worker
  21  * list. A worker which exits with a return code of 1 will be restarted after
  22  * the configured restart interval (unless that interval is BGW_NEVER_RESTART).
  23  * The TerminateBackgroundWorker() function can be used to terminate a
  24  * dynamically registered background worker; the worker will be sent a SIGTERM
  25  * and will not be restarted after it exits.  Whenever the postmaster knows
  26  * that a worker will not be restarted, it unregisters the worker, freeing up
  27  * that worker's slot for use by a new worker.
  28  *
  29  * Note that there might be more than one worker in a database concurrently,
  30  * and the same module may request more than one worker running the same (or
  31  * different) code.
  32  *
  33  *
  34  * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
  35  * Portions Copyright (c) 1994, Regents of the University of California
  36  *
  37  * IDENTIFICATION
  38  *              src/include/postmaster/bgworker.h
  39  *--------------------------------------------------------------------
  40  */
  41 #ifndef BGWORKER_H
  42 #define BGWORKER_H
  43
  44 /*---------------------------------------------------------------------
  45  * External module API.
  46  *---------------------------------------------------------------------
  47  */
  48
  49 /*
  50  * Pass this flag to have your worker be able to connect to shared memory.
  51  * This flag is required.
  52  */
  53 #define BGWORKER_SHMEM_ACCESS                                           0x0001
  54
  55 /*
  56  * This flag means the bgworker requires a database connection.  The connection
  57  * is not established automatically; the worker must establish it later.
  58  * It requires that BGWORKER_SHMEM_ACCESS was passed too.
  59  */
  60 #define BGWORKER_BACKEND_DATABASE_CONNECTION            0x0002
  61
  62 /*
  63  * This class is used internally for parallel queries, to keep track of the
  64  * number of active parallel workers and make sure we never launch more than
  65  * max_parallel_workers parallel workers at the same time.  Third party
  66  * background workers should not use this class.
  67  */
  68 #define BGWORKER_CLASS_PARALLEL                                 0x0010
  69 /* add additional bgworker classes here */
  70
  71
  72 typedef void (*bgworker_main_type) (Datum main_arg);
  73
  74 /*
  75  * Points in time at which a bgworker can request to be started
  76  */
  77 typedef enum
  78 {
  79         BgWorkerStart_PostmasterStart,
  80         BgWorkerStart_ConsistentState,
  81         BgWorkerStart_RecoveryFinished,
  82 } BgWorkerStartTime;
  83
  84 #define BGW_DEFAULT_RESTART_INTERVAL    60
  85 #define BGW_NEVER_RESTART                               -1
  86 #define BGW_MAXLEN                                              96
  87 #define BGW_EXTRALEN                                    128
  88
  89 typedef struct BackgroundWorker
  90 {
  91         char            bgw_name[BGW_MAXLEN];
  92         char            bgw_type[BGW_MAXLEN];
  93         int                     bgw_flags;
  94         BgWorkerStartTime bgw_start_time;
  95         int                     bgw_restart_time;       /* in seconds, or BGW_NEVER_RESTART */
  96         char            bgw_library_name[MAXPGPATH];
  97         char            bgw_function_name[BGW_MAXLEN];
  98         Datum           bgw_main_arg;
  99         char            bgw_extra[BGW_EXTRALEN];
 100         pid_t           bgw_notify_pid; /* SIGUSR1 this backend on start/stop */
 101 } BackgroundWorker;
 102
 103 typedef enum BgwHandleStatus
 104 {
 105         BGWH_STARTED,                           /* worker is running */
 106         BGWH_NOT_YET_STARTED,           /* worker hasn't been started yet */
 107         BGWH_STOPPED,                           /* worker has exited */
 108         BGWH_POSTMASTER_DIED,           /* postmaster died; worker status unclear */
 109 } BgwHandleStatus;
 110
 111 struct BackgroundWorkerHandle;
 112 typedef struct BackgroundWorkerHandle BackgroundWorkerHandle;
 113
 114 /* Register a new bgworker during shared_preload_libraries */
 115 extern void RegisterBackgroundWorker(BackgroundWorker *worker);
 116
 117 /* Register a new bgworker from a regular backend */
 118 extern bool RegisterDynamicBackgroundWorker(BackgroundWorker *worker,
 119                                                                                         BackgroundWorkerHandle **handle);
 120
 121 /* Query the status of a bgworker */
 122 extern BgwHandleStatus GetBackgroundWorkerPid(BackgroundWorkerHandle *handle,
 123                                                                                           pid_t *pidp);
 124 extern BgwHandleStatus WaitForBackgroundWorkerStartup(BackgroundWorkerHandle *handle, pid_t *pidp);
 125 extern BgwHandleStatus
 126                         WaitForBackgroundWorkerShutdown(BackgroundWorkerHandle *);
 127 extern const char *GetBackgroundWorkerTypeByPid(pid_t pid);
 128
 129 /* Terminate a bgworker */
 130 extern void TerminateBackgroundWorker(BackgroundWorkerHandle *handle);
 131
 132 /* This is valid in a running worker */
 133 extern PGDLLIMPORT BackgroundWorker *MyBgworkerEntry;
 134
 135 /*
 136  * Connect to the specified database, as the specified user.  Only a worker
 137  * that passed BGWORKER_BACKEND_DATABASE_CONNECTION during registration may
 138  * call this.
 139  *
 140  * If username is NULL, bootstrapping superuser is used.
 141  * If dbname is NULL, connection is made to no specific database;
 142  * only shared catalogs can be accessed.
 143  */
 144 extern void BackgroundWorkerInitializeConnection(const char *dbname, const char *username, uint32 flags);
 145
 146 /* Just like the above, but specifying database and user by OID. */
 147 extern void BackgroundWorkerInitializeConnectionByOid(Oid dboid, Oid useroid, uint32 flags);
 148
 149 /*
 150  * Flags to BackgroundWorkerInitializeConnection et al
 151  *
 152  *
 153  * Allow bypassing datallowconn restrictions and login check when connecting
 154  * to database
 155  */
 156 #define BGWORKER_BYPASS_ALLOWCONN 0x0001
 157 #define BGWORKER_BYPASS_ROLELOGINCHECK 0x0002
 158
 159
 160 /* Block/unblock signals in a background worker process */
 161 extern void BackgroundWorkerBlockSignals(void);
 162 extern void BackgroundWorkerUnblockSignals(void);
 163
 164 #endif                                                  /* BGWORKER_H */