bgworker.h File Reference

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	BackgroundWorker

Macros
#define	BGWORKER_SHMEM_ACCESS   0x0001
#define	BGWORKER_BACKEND_DATABASE_CONNECTION   0x0002
#define	BGWORKER_CLASS_PARALLEL   0x0010
#define	BGW_DEFAULT_RESTART_INTERVAL   60
#define	BGW_NEVER_RESTART   -1
#define	BGW_MAXLEN   96
#define	BGW_EXTRALEN   128
#define	BGWORKER_BYPASS_ALLOWCONN   1

Typedefs
typedef void(*	bgworker_main_type) (Datum main_arg)
typedef struct BackgroundWorker	BackgroundWorker
typedef enum BgwHandleStatus	BgwHandleStatus
typedef struct BackgroundWorkerHandle	BackgroundWorkerHandle

Enumerations
enum	BgWorkerStartTime { BgWorkerStart_PostmasterStart , BgWorkerStart_ConsistentState , BgWorkerStart_RecoveryFinished }
enum	BgwHandleStatus { BGWH_STARTED , BGWH_NOT_YET_STARTED , BGWH_STOPPED , BGWH_POSTMASTER_DIED }

Functions
void	RegisterBackgroundWorker (BackgroundWorker *worker)
bool	RegisterDynamicBackgroundWorker (BackgroundWorker *worker, BackgroundWorkerHandle **handle)
BgwHandleStatus	GetBackgroundWorkerPid (BackgroundWorkerHandle *handle, pid_t *pidp)
BgwHandleStatus	WaitForBackgroundWorkerStartup (BackgroundWorkerHandle *handle, pid_t *pidp)
BgwHandleStatus	WaitForBackgroundWorkerShutdown (BackgroundWorkerHandle *)
const char *	GetBackgroundWorkerTypeByPid (pid_t pid)
void	TerminateBackgroundWorker (BackgroundWorkerHandle *handle)
void	BackgroundWorkerInitializeConnection (const char *dbname, const char *username, uint32 flags)
void	BackgroundWorkerInitializeConnectionByOid (Oid dboid, Oid useroid, uint32 flags)
void	BackgroundWorkerBlockSignals (void)
void	BackgroundWorkerUnblockSignals (void)

Variables
PGDLLIMPORT BackgroundWorker *	MyBgworkerEntry

Macro Definition Documentation

BGW_DEFAULT_RESTART_INTERVAL

#define BGW_DEFAULT_RESTART_INTERVAL   60

Definition at line 84 of file bgworker.h.

BGW_EXTRALEN

#define BGW_EXTRALEN   128

Definition at line 87 of file bgworker.h.

BGW_MAXLEN

#define BGW_MAXLEN   96

Definition at line 86 of file bgworker.h.

BGW_NEVER_RESTART

#define BGW_NEVER_RESTART   -1

Definition at line 85 of file bgworker.h.

BGWORKER_BACKEND_DATABASE_CONNECTION

#define BGWORKER_BACKEND_DATABASE_CONNECTION   0x0002

Definition at line 60 of file bgworker.h.

BGWORKER_BYPASS_ALLOWCONN

#define BGWORKER_BYPASS_ALLOWCONN   1

Definition at line 155 of file bgworker.h.

BGWORKER_CLASS_PARALLEL

#define BGWORKER_CLASS_PARALLEL   0x0010

Definition at line 68 of file bgworker.h.

BGWORKER_SHMEM_ACCESS

#define BGWORKER_SHMEM_ACCESS   0x0001

Definition at line 53 of file bgworker.h.

Typedef Documentation

BackgroundWorker

typedef struct BackgroundWorker BackgroundWorker

BackgroundWorkerHandle

typedef struct BackgroundWorkerHandle BackgroundWorkerHandle

Definition at line 72 of file bgworker.h.

BgwHandleStatus

typedef enum BgwHandleStatus BgwHandleStatus

bgworker_main_type

typedef void(* bgworker_main_type) (Datum main_arg)

Definition at line 72 of file bgworker.h.

Enumeration Type Documentation

BgwHandleStatus

enum BgwHandleStatus

Enumerator
BGWH_STARTED
BGWH_NOT_YET_STARTED
BGWH_STOPPED
BGWH_POSTMASTER_DIED

Definition at line 103 of file bgworker.h.

{
    BGWH_STARTED,               /* worker is running */
    BGWH_NOT_YET_STARTED,       /* worker hasn't been started yet */
    BGWH_STOPPED,               /* worker has exited */
    BGWH_POSTMASTER_DIED        /* postmaster died; worker status unclear */
} BgwHandleStatus;

BgWorkerStartTime

enum BgWorkerStartTime

Enumerator
BgWorkerStart_PostmasterStart
BgWorkerStart_ConsistentState
BgWorkerStart_RecoveryFinished

Definition at line 77 of file bgworker.h.

{
    BgWorkerStart_PostmasterStart,
    BgWorkerStart_ConsistentState,
    BgWorkerStart_RecoveryFinished
} BgWorkerStartTime;

Function Documentation

BackgroundWorkerBlockSignals()

void BackgroundWorkerBlockSignals

(

void

)

Definition at line 5654 of file postmaster.c.

{
    sigprocmask(SIG_SETMASK, &BlockSig, NULL);
}

References BlockSig.

BackgroundWorkerInitializeConnection()

void BackgroundWorkerInitializeConnection	(	const char *	dbname,
		const char *	username,
		uint32	flags
	)

Definition at line 5600 of file postmaster.c.

{
    BackgroundWorker *worker = MyBgworkerEntry;
 
    /* XXX is this the right errcode? */
    if (!(worker->bgw_flags & BGWORKER_BACKEND_DATABASE_CONNECTION))
        ereport(FATAL,
                (errcode(ERRCODE_PROGRAM_LIMIT_EXCEEDED),
                 errmsg("database connection requirement not indicated during registration")));
 
    InitPostgres(dbname, InvalidOid,    /* database to connect to */
                 username, InvalidOid,  /* role to connect as */
                 false,         /* never honor session_preload_libraries */
                 (flags & BGWORKER_BYPASS_ALLOWCONN) != 0,  /* ignore datallowconn? */
                 NULL);         /* no out_dbname */
 
    /* it had better not gotten out of "init" mode yet */
    if (!IsInitProcessingMode())
        ereport(ERROR,
                (errmsg("invalid processing mode in background worker")));
    SetProcessingMode(NormalProcessing);
}

References BackgroundWorker::bgw_flags, BGWORKER_BACKEND_DATABASE_CONNECTION, BGWORKER_BYPASS_ALLOWCONN, dbname, ereport, errcode(), errmsg(), ERROR, FATAL, InitPostgres(), InvalidOid, IsInitProcessingMode, MyBgworkerEntry, NormalProcessing, SetProcessingMode, and username.

Referenced by ApplyLauncherMain(), and worker_spi_main().

BackgroundWorkerInitializeConnectionByOid()

void BackgroundWorkerInitializeConnectionByOid	(	Oid	dboid,
		Oid	useroid,
		uint32	flags
	)

Definition at line 5627 of file postmaster.c.

{
    BackgroundWorker *worker = MyBgworkerEntry;
 
    /* XXX is this the right errcode? */
    if (!(worker->bgw_flags & BGWORKER_BACKEND_DATABASE_CONNECTION))
        ereport(FATAL,
                (errcode(ERRCODE_PROGRAM_LIMIT_EXCEEDED),
                 errmsg("database connection requirement not indicated during registration")));
 
    InitPostgres(NULL, dboid,   /* database to connect to */
                 NULL, useroid, /* role to connect as */
                 false,         /* never honor session_preload_libraries */
                 (flags & BGWORKER_BYPASS_ALLOWCONN) != 0,  /* ignore datallowconn? */
                 NULL);         /* no out_dbname */
 
    /* it had better not gotten out of "init" mode yet */
    if (!IsInitProcessingMode())
        ereport(ERROR,
                (errmsg("invalid processing mode in background worker")));
    SetProcessingMode(NormalProcessing);
}

References BackgroundWorker::bgw_flags, BGWORKER_BACKEND_DATABASE_CONNECTION, BGWORKER_BYPASS_ALLOWCONN, ereport, errcode(), errmsg(), ERROR, FATAL, InitPostgres(), IsInitProcessingMode, MyBgworkerEntry, NormalProcessing, and SetProcessingMode.

Referenced by autoprewarm_database_main(), InitializeApplyWorker(), and ParallelWorkerMain().

BackgroundWorkerUnblockSignals()

void BackgroundWorkerUnblockSignals

(

void

)

Definition at line 5660 of file postmaster.c.

{
    sigprocmask(SIG_SETMASK, &UnBlockSig, NULL);
}

References UnBlockSig.

Referenced by ApplyLauncherMain(), ApplyWorkerMain(), autoprewarm_database_main(), autoprewarm_main(), ParallelApplyWorkerMain(), ParallelWorkerMain(), StartBackgroundWorker(), test_shm_mq_main(), and worker_spi_main().

GetBackgroundWorkerPid()

BgwHandleStatus GetBackgroundWorkerPid	(	BackgroundWorkerHandle *	handle,
		pid_t *	pidp
	)

Definition at line 1071 of file bgworker.c.

{
    BackgroundWorkerSlot *slot;
    pid_t       pid;
 
    Assert(handle->slot < max_worker_processes);
    slot = &BackgroundWorkerData->slot[handle->slot];
 
    /*
     * We could probably arrange to synchronize access to data using memory
     * barriers only, but for now, let's just keep it simple and grab the
     * lock.  It seems unlikely that there will be enough traffic here to
     * result in meaningful contention.
     */
    LWLockAcquire(BackgroundWorkerLock, LW_SHARED);
 
    /*
     * The generation number can't be concurrently changed while we hold the
     * lock.  The pid, which is updated by the postmaster, can change at any
     * time, but we assume such changes are atomic.  So the value we read
     * won't be garbage, but it might be out of date by the time the caller
     * examines it (but that's unavoidable anyway).
     *
     * The in_use flag could be in the process of changing from true to false,
     * but if it is already false then it can't change further.
     */
    if (handle->generation != slot->generation || !slot->in_use)
        pid = 0;
    else
        pid = slot->pid;
 
    /* All done. */
    LWLockRelease(BackgroundWorkerLock);
 
    if (pid == 0)
        return BGWH_STOPPED;
    else if (pid == InvalidPid)
        return BGWH_NOT_YET_STARTED;
    *pidp = pid;
    return BGWH_STARTED;
}

References Assert(), BackgroundWorkerData, BGWH_NOT_YET_STARTED, BGWH_STARTED, BGWH_STOPPED, BackgroundWorkerSlot::generation, BackgroundWorkerHandle::generation, BackgroundWorkerSlot::in_use, InvalidPid, LW_SHARED, LWLockAcquire(), LWLockRelease(), max_worker_processes, BackgroundWorkerSlot::pid, BackgroundWorkerArray::slot, and BackgroundWorkerHandle::slot.

Referenced by check_worker_status(), shm_mq_counterparty_gone(), shm_mq_wait_internal(), WaitForBackgroundWorkerShutdown(), WaitForBackgroundWorkerStartup(), WaitForParallelWorkersToAttach(), WaitForParallelWorkersToFinish(), and WaitForReplicationWorkerAttach().

GetBackgroundWorkerTypeByPid()

const char* GetBackgroundWorkerTypeByPid

(

pid_t

pid

)

Definition at line 1285 of file bgworker.c.

{
    int         slotno;
    bool        found = false;
    static char result[BGW_MAXLEN];
 
    LWLockAcquire(BackgroundWorkerLock, LW_SHARED);
 
    for (slotno = 0; slotno < BackgroundWorkerData->total_slots; slotno++)
    {
        BackgroundWorkerSlot *slot = &BackgroundWorkerData->slot[slotno];
 
        if (slot->pid > 0 && slot->pid == pid)
        {
            strcpy(result, slot->worker.bgw_type);
            found = true;
            break;
        }
    }
 
    LWLockRelease(BackgroundWorkerLock);
 
    if (!found)
        return NULL;
 
    return result;
}

References BackgroundWorkerData, BGW_MAXLEN, BackgroundWorker::bgw_type, LW_SHARED, LWLockAcquire(), LWLockRelease(), BackgroundWorkerSlot::pid, BackgroundWorkerArray::slot, BackgroundWorkerArray::total_slots, and BackgroundWorkerSlot::worker.

Referenced by pg_stat_get_activity().

RegisterBackgroundWorker()

void RegisterBackgroundWorker

(

BackgroundWorker *

worker

)

Definition at line 875 of file bgworker.c.

{
    RegisteredBgWorker *rw;
    static int  numworkers = 0;
 
    if (!IsUnderPostmaster)
        ereport(DEBUG1,
                (errmsg_internal("registering background worker \"%s\"", worker->bgw_name)));
 
    if (!process_shared_preload_libraries_in_progress &&
        strcmp(worker->bgw_library_name, "postgres") != 0)
    {
        if (!IsUnderPostmaster)
            ereport(LOG,
                    (errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
                     errmsg("background worker \"%s\": must be registered in shared_preload_libraries",
                            worker->bgw_name)));
        return;
    }
 
    if (!SanityCheckBackgroundWorker(worker, LOG))
        return;
 
    if (worker->bgw_notify_pid != 0)
    {
        ereport(LOG,
                (errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
                 errmsg("background worker \"%s\": only dynamic background workers can request notification",
                        worker->bgw_name)));
        return;
    }
 
    /*
     * Enforce maximum number of workers.  Note this is overly restrictive: we
     * could allow more non-shmem-connected workers, because these don't count
     * towards the MAX_BACKENDS limit elsewhere.  For now, it doesn't seem
     * important to relax this restriction.
     */
    if (++numworkers > max_worker_processes)
    {
        ereport(LOG,
                (errcode(ERRCODE_CONFIGURATION_LIMIT_EXCEEDED),
                 errmsg("too many background workers"),
                 errdetail_plural("Up to %d background worker can be registered with the current settings.",
                                  "Up to %d background workers can be registered with the current settings.",
                                  max_worker_processes,
                                  max_worker_processes),
                 errhint("Consider increasing the configuration parameter \"max_worker_processes\".")));
        return;
    }
 
    /*
     * Copy the registration data into the registered workers list.
     */
    rw = malloc(sizeof(RegisteredBgWorker));
    if (rw == NULL)
    {
        ereport(LOG,
                (errcode(ERRCODE_OUT_OF_MEMORY),
                 errmsg("out of memory")));
        return;
    }
 
    rw->rw_worker = *worker;
    rw->rw_backend = NULL;
    rw->rw_pid = 0;
    rw->rw_child_slot = 0;
    rw->rw_crashed_at = 0;
    rw->rw_terminate = false;
 
    slist_push_head(&BackgroundWorkerList, &rw->rw_lnode);
}

References BackgroundWorkerList, BackgroundWorker::bgw_library_name, BackgroundWorker::bgw_name, BackgroundWorker::bgw_notify_pid, DEBUG1, ereport, errcode(), errdetail_plural(), errhint(), errmsg(), errmsg_internal(), IsUnderPostmaster, LOG, malloc, max_worker_processes, process_shared_preload_libraries_in_progress, RegisteredBgWorker::rw_backend, RegisteredBgWorker::rw_child_slot, RegisteredBgWorker::rw_crashed_at, RegisteredBgWorker::rw_lnode, RegisteredBgWorker::rw_pid, RegisteredBgWorker::rw_terminate, RegisteredBgWorker::rw_worker, SanityCheckBackgroundWorker(), and slist_push_head().

Referenced by _PG_init(), ApplyLauncherRegister(), and apw_start_leader_worker().

RegisterDynamicBackgroundWorker()

bool RegisterDynamicBackgroundWorker	(	BackgroundWorker *	worker,
		BackgroundWorkerHandle **	handle
	)

Definition at line 959 of file bgworker.c.

{
    int         slotno;
    bool        success = false;
    bool        parallel;
    uint64      generation = 0;
 
    /*
     * We can't register dynamic background workers from the postmaster. If
     * this is a standalone backend, we're the only process and can't start
     * any more.  In a multi-process environment, it might be theoretically
     * possible, but we don't currently support it due to locking
     * considerations; see comments on the BackgroundWorkerSlot data
     * structure.
     */
    if (!IsUnderPostmaster)
        return false;
 
    if (!SanityCheckBackgroundWorker(worker, ERROR))
        return false;
 
    parallel = (worker->bgw_flags & BGWORKER_CLASS_PARALLEL) != 0;
 
    LWLockAcquire(BackgroundWorkerLock, LW_EXCLUSIVE);
 
    /*
     * If this is a parallel worker, check whether there are already too many
     * parallel workers; if so, don't register another one.  Our view of
     * parallel_terminate_count may be slightly stale, but that doesn't really
     * matter: we would have gotten the same result if we'd arrived here
     * slightly earlier anyway.  There's no help for it, either, since the
     * postmaster must not take locks; a memory barrier wouldn't guarantee
     * anything useful.
     */
    if (parallel && (BackgroundWorkerData->parallel_register_count -
                     BackgroundWorkerData->parallel_terminate_count) >=
        max_parallel_workers)
    {
        Assert(BackgroundWorkerData->parallel_register_count -
               BackgroundWorkerData->parallel_terminate_count <=
               MAX_PARALLEL_WORKER_LIMIT);
        LWLockRelease(BackgroundWorkerLock);
        return false;
    }
 
    /*
     * Look for an unused slot.  If we find one, grab it.
     */
    for (slotno = 0; slotno < BackgroundWorkerData->total_slots; ++slotno)
    {
        BackgroundWorkerSlot *slot = &BackgroundWorkerData->slot[slotno];
 
        if (!slot->in_use)
        {
            memcpy(&slot->worker, worker, sizeof(BackgroundWorker));
            slot->pid = InvalidPid; /* indicates not started yet */
            slot->generation++;
            slot->terminate = false;
            generation = slot->generation;
            if (parallel)
                BackgroundWorkerData->parallel_register_count++;
 
            /*
             * Make sure postmaster doesn't see the slot as in use before it
             * sees the new contents.
             */
            pg_write_barrier();
 
            slot->in_use = true;
            success = true;
            break;
        }
    }
 
    LWLockRelease(BackgroundWorkerLock);
 
    /* If we found a slot, tell the postmaster to notice the change. */
    if (success)
        SendPostmasterSignal(PMSIGNAL_BACKGROUND_WORKER_CHANGE);
 
    /*
     * If we found a slot and the user has provided a handle, initialize it.
     */
    if (success && handle)
    {
        *handle = palloc(sizeof(BackgroundWorkerHandle));
        (*handle)->slot = slotno;
        (*handle)->generation = generation;
    }
 
    return success;
}

References Assert(), BackgroundWorkerData, BackgroundWorker::bgw_flags, BGWORKER_CLASS_PARALLEL, ERROR, BackgroundWorkerSlot::generation, BackgroundWorkerSlot::in_use, InvalidPid, IsUnderPostmaster, LW_EXCLUSIVE, LWLockAcquire(), LWLockRelease(), MAX_PARALLEL_WORKER_LIMIT, max_parallel_workers, palloc(), BackgroundWorkerArray::parallel_register_count, BackgroundWorkerArray::parallel_terminate_count, pg_write_barrier, BackgroundWorkerSlot::pid, PMSIGNAL_BACKGROUND_WORKER_CHANGE, SanityCheckBackgroundWorker(), SendPostmasterSignal(), BackgroundWorkerArray::slot, success, BackgroundWorkerSlot::terminate, BackgroundWorkerArray::total_slots, and BackgroundWorkerSlot::worker.

Referenced by apw_start_database_worker(), apw_start_leader_worker(), LaunchParallelWorkers(), logicalrep_worker_launch(), setup_background_workers(), and worker_spi_launch().

TerminateBackgroundWorker()

void TerminateBackgroundWorker

(

BackgroundWorkerHandle *

handle

)

Definition at line 1210 of file bgworker.c.

{
    BackgroundWorkerSlot *slot;
    bool        signal_postmaster = false;
 
    Assert(handle->slot < max_worker_processes);
    slot = &BackgroundWorkerData->slot[handle->slot];
 
    /* Set terminate flag in shared memory, unless slot has been reused. */
    LWLockAcquire(BackgroundWorkerLock, LW_EXCLUSIVE);
    if (handle->generation == slot->generation)
    {
        slot->terminate = true;
        signal_postmaster = true;
    }
    LWLockRelease(BackgroundWorkerLock);
 
    /* Make sure the postmaster notices the change to shared memory. */
    if (signal_postmaster)
        SendPostmasterSignal(PMSIGNAL_BACKGROUND_WORKER_CHANGE);
}

References Assert(), BackgroundWorkerData, BackgroundWorkerSlot::generation, BackgroundWorkerHandle::generation, LW_EXCLUSIVE, LWLockAcquire(), LWLockRelease(), max_worker_processes, PMSIGNAL_BACKGROUND_WORKER_CHANGE, SendPostmasterSignal(), BackgroundWorkerArray::slot, BackgroundWorkerHandle::slot, and BackgroundWorkerSlot::terminate.

Referenced by cleanup_background_workers(), and DestroyParallelContext().

WaitForBackgroundWorkerShutdown()

BgwHandleStatus WaitForBackgroundWorkerShutdown

(

BackgroundWorkerHandle *

handle

)

Definition at line 1171 of file bgworker.c.

{
    BgwHandleStatus status;
    int         rc;
 
    for (;;)
    {
        pid_t       pid;
 
        CHECK_FOR_INTERRUPTS();
 
        status = GetBackgroundWorkerPid(handle, &pid);
        if (status == BGWH_STOPPED)
            break;
 
        rc = WaitLatch(MyLatch,
                       WL_LATCH_SET | WL_POSTMASTER_DEATH, 0,
                       WAIT_EVENT_BGWORKER_SHUTDOWN);
 
        if (rc & WL_POSTMASTER_DEATH)
        {
            status = BGWH_POSTMASTER_DIED;
            break;
        }
 
        ResetLatch(MyLatch);
    }
 
    return status;
}

References BGWH_POSTMASTER_DIED, BGWH_STOPPED, CHECK_FOR_INTERRUPTS, GetBackgroundWorkerPid(), MyLatch, ResetLatch(), WAIT_EVENT_BGWORKER_SHUTDOWN, WaitLatch(), WL_LATCH_SET, and WL_POSTMASTER_DEATH.

Referenced by apw_start_database_worker(), and WaitForParallelWorkersToExit().

WaitForBackgroundWorkerStartup()

BgwHandleStatus WaitForBackgroundWorkerStartup	(	BackgroundWorkerHandle *	handle,
		pid_t *	pidp
	)

Definition at line 1126 of file bgworker.c.

{
    BgwHandleStatus status;
    int         rc;
 
    for (;;)
    {
        pid_t       pid;
 
        CHECK_FOR_INTERRUPTS();
 
        status = GetBackgroundWorkerPid(handle, &pid);
        if (status == BGWH_STARTED)
            *pidp = pid;
        if (status != BGWH_NOT_YET_STARTED)
            break;
 
        rc = WaitLatch(MyLatch,
                       WL_LATCH_SET | WL_POSTMASTER_DEATH, 0,
                       WAIT_EVENT_BGWORKER_STARTUP);
 
        if (rc & WL_POSTMASTER_DEATH)
        {
            status = BGWH_POSTMASTER_DIED;
            break;
        }
 
        ResetLatch(MyLatch);
    }
 
    return status;
}

References BGWH_NOT_YET_STARTED, BGWH_POSTMASTER_DIED, BGWH_STARTED, CHECK_FOR_INTERRUPTS, GetBackgroundWorkerPid(), MyLatch, ResetLatch(), WAIT_EVENT_BGWORKER_STARTUP, WaitLatch(), WL_LATCH_SET, and WL_POSTMASTER_DEATH.

Referenced by apw_start_leader_worker(), and worker_spi_launch().

Variable Documentation

MyBgworkerEntry

PGDLLIMPORT BackgroundWorker* MyBgworkerEntry

extern

Definition at line 193 of file postmaster.c.

Referenced by BackgroundWorkerInitializeConnection(), BackgroundWorkerInitializeConnectionByOid(), bgworker_die(), do_start_bgworker(), get_backend_type_for_log(), ParallelApplyWorkerMain(), ParallelWorkerMain(), ProcessInterrupts(), StartBackgroundWorker(), test_shm_mq_main(), and worker_spi_main().