PostgreSQL Source Code  git master
bgworker.h
Go to the documentation of this file.
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-2024, 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 {
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 {
93  int bgw_flags;
95  int bgw_restart_time; /* in seconds, or BGW_NEVER_RESTART */
100  pid_t bgw_notify_pid; /* SIGUSR1 this backend on start/stop */
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 */
110 
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 */
119  BackgroundWorkerHandle **handle);
120 
121 /* Query the status of a bgworker */
123  pid_t *pidp);
125 extern BgwHandleStatus
127 extern const char *GetBackgroundWorkerTypeByPid(pid_t pid);
128 
129 /* Terminate a bgworker */
131 
132 /* This is valid in a running worker */
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 */
void RegisterBackgroundWorker(BackgroundWorker *worker)
Definition: bgworker.c:862
BgwHandleStatus WaitForBackgroundWorkerStartup(BackgroundWorkerHandle *handle, pid_t *pidp)
Definition: bgworker.c:1137
BgwHandleStatus WaitForBackgroundWorkerShutdown(BackgroundWorkerHandle *)
Definition: bgworker.c:1182
void BackgroundWorkerInitializeConnection(const char *dbname, const char *username, uint32 flags)
Definition: postmaster.c:4155
#define BGW_EXTRALEN
Definition: bgworker.h:87
void TerminateBackgroundWorker(BackgroundWorkerHandle *handle)
Definition: bgworker.c:1221
void BackgroundWorkerUnblockSignals(void)
Definition: postmaster.c:4229
void BackgroundWorkerInitializeConnectionByOid(Oid dboid, Oid useroid, uint32 flags)
Definition: postmaster.c:4189
BgwHandleStatus
Definition: bgworker.h:104
@ BGWH_POSTMASTER_DIED
Definition: bgworker.h:108
@ BGWH_STARTED
Definition: bgworker.h:105
@ BGWH_NOT_YET_STARTED
Definition: bgworker.h:106
@ BGWH_STOPPED
Definition: bgworker.h:107
BgWorkerStartTime
Definition: bgworker.h:78
@ BgWorkerStart_RecoveryFinished
Definition: bgworker.h:81
@ BgWorkerStart_ConsistentState
Definition: bgworker.h:80
@ BgWorkerStart_PostmasterStart
Definition: bgworker.h:79
void BackgroundWorkerBlockSignals(void)
Definition: postmaster.c:4223
const char * GetBackgroundWorkerTypeByPid(pid_t pid)
Definition: bgworker.c:1296
struct BackgroundWorker BackgroundWorker
BgwHandleStatus GetBackgroundWorkerPid(BackgroundWorkerHandle *handle, pid_t *pidp)
Definition: bgworker.c:1082
PGDLLIMPORT BackgroundWorker * MyBgworkerEntry
Definition: postmaster.c:185
void(* bgworker_main_type)(Datum main_arg)
Definition: bgworker.h:72
#define BGW_MAXLEN
Definition: bgworker.h:86
bool RegisterDynamicBackgroundWorker(BackgroundWorker *worker, BackgroundWorkerHandle **handle)
Definition: bgworker.c:970
unsigned int uint32
Definition: c.h:493
#define PGDLLIMPORT
Definition: c.h:1303
#define MAXPGPATH
const char * username
Definition: pgbench.c:296
uintptr_t Datum
Definition: postgres.h:64
unsigned int Oid
Definition: postgres_ext.h:31
char * dbname
Definition: streamutil.c:52
char bgw_function_name[BGW_MAXLEN]
Definition: bgworker.h:97
Datum bgw_main_arg
Definition: bgworker.h:98
char bgw_name[BGW_MAXLEN]
Definition: bgworker.h:91
int bgw_restart_time
Definition: bgworker.h:95
char bgw_type[BGW_MAXLEN]
Definition: bgworker.h:92
BgWorkerStartTime bgw_start_time
Definition: bgworker.h:94
char bgw_extra[BGW_EXTRALEN]
Definition: bgworker.h:99
pid_t bgw_notify_pid
Definition: bgworker.h:100
char bgw_library_name[MAXPGPATH]
Definition: bgworker.h:96