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-2018, 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 */ 52 #define BGWORKER_SHMEM_ACCESS 0x0001 53 54 /* 55 * This flag means the bgworker requires a database connection. The connection 56 * is not established automatically; the worker must establish it later. 57 * It requires that BGWORKER_SHMEM_ACCESS was passed too. 58 */ 59 #define BGWORKER_BACKEND_DATABASE_CONNECTION 0x0002 60 61 /* 62 * This class is used internally for parallel queries, to keep track of the 63 * number of active parallel workers and make sure we never launch more than 64 * max_parallel_workers parallel workers at the same time. Third party 65 * background workers should not use this class. 66 */ 67 #define BGWORKER_CLASS_PARALLEL 0x0010 68 /* add additional bgworker classes here */ 69 70 71 typedef void (*bgworker_main_type) (Datum main_arg); 72 73 /* 74 * Points in time at which a bgworker can request to be started 75 */ 76 typedef enum 77 { 78 BgWorkerStart_PostmasterStart, 79 BgWorkerStart_ConsistentState, 80 BgWorkerStart_RecoveryFinished 81 } BgWorkerStartTime; 82 83 #define BGW_DEFAULT_RESTART_INTERVAL 60 84 #define BGW_NEVER_RESTART -1 85 #define BGW_MAXLEN 96 86 #define BGW_EXTRALEN 128 87 88 typedef struct BackgroundWorker 89 { 90 char bgw_name[BGW_MAXLEN]; 91 char bgw_type[BGW_MAXLEN]; 92 int bgw_flags; 93 BgWorkerStartTime bgw_start_time; 94 int bgw_restart_time; /* in seconds, or BGW_NEVER_RESTART */ 95 char bgw_library_name[BGW_MAXLEN]; 96 char bgw_function_name[BGW_MAXLEN]; 97 Datum bgw_main_arg; 98 char bgw_extra[BGW_EXTRALEN]; 99 pid_t bgw_notify_pid; /* SIGUSR1 this backend on start/stop */ 100 } BackgroundWorker; 101 102 typedef enum BgwHandleStatus 103 { 104 BGWH_STARTED, /* worker is running */ 105 BGWH_NOT_YET_STARTED, /* worker hasn't been started yet */ 106 BGWH_STOPPED, /* worker has exited */ 107 BGWH_POSTMASTER_DIED /* postmaster died; worker status unclear */ 108 } BgwHandleStatus; 109 110 struct BackgroundWorkerHandle; 111 typedef struct BackgroundWorkerHandle BackgroundWorkerHandle; 112 113 /* Register a new bgworker during shared_preload_libraries */ 114 extern void RegisterBackgroundWorker(BackgroundWorker *worker); 115 116 /* Register a new bgworker from a regular backend */ 117 extern bool RegisterDynamicBackgroundWorker(BackgroundWorker *worker, 118 BackgroundWorkerHandle **handle); 119 120 /* Query the status of a bgworker */ 121 extern BgwHandleStatus GetBackgroundWorkerPid(BackgroundWorkerHandle *handle, 122 pid_t *pidp); 123 extern BgwHandleStatus WaitForBackgroundWorkerStartup(BackgroundWorkerHandle *handle, pid_t *pid); 124 extern BgwHandleStatus 125 WaitForBackgroundWorkerShutdown(BackgroundWorkerHandle *); 126 extern const char *GetBackgroundWorkerTypeByPid(pid_t pid); 127 128 /* Terminate a bgworker */ 129 extern void TerminateBackgroundWorker(BackgroundWorkerHandle *handle); 130 131 /* This is valid in a running worker */ 132 extern PGDLLIMPORT BackgroundWorker *MyBgworkerEntry; 133 134 /* 135 * Connect to the specified database, as the specified user. Only a worker 136 * that passed BGWORKER_BACKEND_DATABASE_CONNECTION during registration may 137 * call this. 138 * 139 * If username is NULL, bootstrapping superuser is used. 140 * If dbname is NULL, connection is made to no specific database; 141 * only shared catalogs can be accessed. 142 */ 143 extern void BackgroundWorkerInitializeConnection(const char *dbname, const char *username, uint32 flags); 144 145 /* Just like the above, but specifying database and user by OID. */ 146 extern void BackgroundWorkerInitializeConnectionByOid(Oid dboid, Oid useroid, uint32 flags); 147 148 /* 149 * Flags to BackgroundWorkerInitializeConnection et al 150 * 151 * 152 * Allow bypassing datallowconn restrictions when connecting to database 153 */ 154 #define BGWORKER_BYPASS_ALLOWCONN 1 155 156 157 /* Block/unblock signals in a background worker process */ 158 extern void BackgroundWorkerBlockSignals(void); 159 extern void BackgroundWorkerUnblockSignals(void); 160 161 #endif /* BGWORKER_H */ 162