codekingpro/portable-devtools

1/*--------------------------------------------------------------------2 * bgworker.h3 *		POSTGRES pluggable background workers interface4 *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 a9 * worker.  Workers can also be registered dynamically at runtime.  In either10 * case, the worker process is forked from the postmaster and runs the11 * user-supplied "main" function.  This code may connect to a database and12 * run transactions.  Workers can remain active indefinitely, but will be13 * terminated if a shutdown or crash occurs.14 *15 * If the fork() call fails in the postmaster, it will try again later.  Note16 * that the failure can only be transient (fork failure due to high load,17 * memory pressure, too many processes, etc); more permanent problems, like18 * failure to connect to a database, are detected later in the worker and dealt19 * with just by having the worker exit normally. A worker which exits with20 * a return code of 0 will never be restarted and will be removed from worker21 * list. A worker which exits with a return code of 1 will be restarted after22 * the configured restart interval (unless that interval is BGW_NEVER_RESTART).23 * The TerminateBackgroundWorker() function can be used to terminate a24 * dynamically registered background worker; the worker will be sent a SIGTERM25 * and will not be restarted after it exits.  Whenever the postmaster knows26 * that a worker will not be restarted, it unregisters the worker, freeing up27 * 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 (or31 * different) code.32 *33 *34 * Portions Copyright (c) 1996-2023, PostgreSQL Global Development Group35 * Portions Copyright (c) 1994, Regents of the University of California36 *37 * IDENTIFICATION38 *		src/include/postmaster/bgworker.h39 *--------------------------------------------------------------------40 */41#ifndef BGWORKER_H42#define BGWORKER_H43 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						0x000154 55/*56 * This flag means the bgworker requires a database connection.  The connection57 * 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		0x000261 62/*63 * This class is used internally for parallel queries, to keep track of the64 * number of active parallel workers and make sure we never launch more than65 * max_parallel_workers parallel workers at the same time.  Third party66 * background workers should not use this class.67 */68#define BGWORKER_CLASS_PARALLEL					0x001069/* add additional bgworker classes here */70 71 72typedef void (*bgworker_main_type) (Datum main_arg);73 74/*75 * Points in time at which a bgworker can request to be started76 */77typedef enum78{79	BgWorkerStart_PostmasterStart,80	BgWorkerStart_ConsistentState,81	BgWorkerStart_RecoveryFinished82} BgWorkerStartTime;83 84#define BGW_DEFAULT_RESTART_INTERVAL	6085#define BGW_NEVER_RESTART				-186#define BGW_MAXLEN						9687#define BGW_EXTRALEN					12888 89typedef struct BackgroundWorker90{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[BGW_MAXLEN];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 103typedef enum BgwHandleStatus104{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 111struct BackgroundWorkerHandle;112typedef struct BackgroundWorkerHandle BackgroundWorkerHandle;113 114/* Register a new bgworker during shared_preload_libraries */115extern void RegisterBackgroundWorker(BackgroundWorker *worker);116 117/* Register a new bgworker from a regular backend */118extern bool RegisterDynamicBackgroundWorker(BackgroundWorker *worker,119											BackgroundWorkerHandle **handle);120 121/* Query the status of a bgworker */122extern BgwHandleStatus GetBackgroundWorkerPid(BackgroundWorkerHandle *handle,123											  pid_t *pidp);124extern BgwHandleStatus WaitForBackgroundWorkerStartup(BackgroundWorkerHandle *handle, pid_t *pidp);125extern BgwHandleStatus126			WaitForBackgroundWorkerShutdown(BackgroundWorkerHandle *);127extern const char *GetBackgroundWorkerTypeByPid(pid_t pid);128 129/* Terminate a bgworker */130extern void TerminateBackgroundWorker(BackgroundWorkerHandle *handle);131 132/* This is valid in a running worker */133extern PGDLLIMPORT BackgroundWorker *MyBgworkerEntry;134 135/*136 * Connect to the specified database, as the specified user.  Only a worker137 * that passed BGWORKER_BACKEND_DATABASE_CONNECTION during registration may138 * 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 */144extern void BackgroundWorkerInitializeConnection(const char *dbname, const char *username, uint32 flags);145 146/* Just like the above, but specifying database and user by OID. */147extern void BackgroundWorkerInitializeConnectionByOid(Oid dboid, Oid useroid, uint32 flags);148 149/*150 * Flags to BackgroundWorkerInitializeConnection et al151 *152 *153 * Allow bypassing datallowconn restrictions when connecting to database154 */155#define BGWORKER_BYPASS_ALLOWCONN 1156 157 158/* Block/unblock signals in a background worker process */159extern void BackgroundWorkerBlockSignals(void);160extern void BackgroundWorkerUnblockSignals(void);161 162#endif							/* BGWORKER_H */163