codekingpro/portable-devtools

1/*-------------------------------------------------------------------------2 *3 * latch.h4 *	  Routines for interprocess latches5 *6 * A latch is a boolean variable, with operations that let processes sleep7 * until it is set. A latch can be set from another process, or a signal8 * handler within the same process.9 *10 * The latch interface is a reliable replacement for the common pattern of11 * using pg_usleep() or select() to wait until a signal arrives, where the12 * signal handler sets a flag variable. Because on some platforms an13 * incoming signal doesn't interrupt sleep, and even on platforms where it14 * does there is a race condition if the signal arrives just before15 * entering the sleep, the common pattern must periodically wake up and16 * poll the flag variable. The pselect() system call was invented to solve17 * this problem, but it is not portable enough. Latches are designed to18 * overcome these limitations, allowing you to sleep without polling and19 * ensuring quick response to signals from other processes.20 *21 * There are two kinds of latches: local and shared. A local latch is22 * initialized by InitLatch, and can only be set from the same process.23 * A local latch can be used to wait for a signal to arrive, by calling24 * SetLatch in the signal handler. A shared latch resides in shared memory,25 * and must be initialized at postmaster startup by InitSharedLatch. Before26 * a shared latch can be waited on, it must be associated with a process27 * with OwnLatch. Only the process owning the latch can wait on it, but any28 * process can set it.29 *30 * There are three basic operations on a latch:31 *32 * SetLatch		- Sets the latch33 * ResetLatch	- Clears the latch, allowing it to be set again34 * WaitLatch	- Waits for the latch to become set35 *36 * WaitLatch includes a provision for timeouts (which should be avoided37 * when possible, as they incur extra overhead) and a provision for38 * postmaster child processes to wake up immediately on postmaster death.39 * See latch.c for detailed specifications for the exported functions.40 *41 * The correct pattern to wait for event(s) is:42 *43 * for (;;)44 * {45 *	   ResetLatch();46 *	   if (work to do)47 *		   Do Stuff();48 *	   WaitLatch();49 * }50 *51 * It's important to reset the latch *before* checking if there's work to52 * do. Otherwise, if someone sets the latch between the check and the53 * ResetLatch call, you will miss it and Wait will incorrectly block.54 *55 * Another valid coding pattern looks like:56 *57 * for (;;)58 * {59 *	   if (work to do)60 *		   Do Stuff(); // in particular, exit loop if some condition satisfied61 *	   WaitLatch();62 *	   ResetLatch();63 * }64 *65 * This is useful to reduce latch traffic if it's expected that the loop's66 * termination condition will often be satisfied in the first iteration;67 * the cost is an extra loop iteration before blocking when it is not.68 * What must be avoided is placing any checks for asynchronous events after69 * WaitLatch and before ResetLatch, as that creates a race condition.70 *71 * To wake up the waiter, you must first set a global flag or something72 * else that the wait loop tests in the "if (work to do)" part, and call73 * SetLatch *after* that. SetLatch is designed to return quickly if the74 * latch is already set.75 *76 * On some platforms, signals will not interrupt the latch wait primitive77 * by themselves.  Therefore, it is critical that any signal handler that78 * is meant to terminate a WaitLatch wait calls SetLatch.79 *80 * Note that use of the process latch (PGPROC.procLatch) is generally better81 * than an ad-hoc shared latch for signaling auxiliary processes.  This is82 * because generic signal handlers will call SetLatch on the process latch83 * only, so using any latch other than the process latch effectively precludes84 * use of any generic handler.85 *86 *87 * WaitEventSets allow to wait for latches being set and additional events -88 * postmaster dying and socket readiness of several sockets currently - at the89 * same time.  On many platforms using a long lived event set is more90 * efficient than using WaitLatch or WaitLatchOrSocket.91 *92 *93 * Portions Copyright (c) 1996-2023, PostgreSQL Global Development Group94 * Portions Copyright (c) 1994, Regents of the University of California95 *96 * src/include/storage/latch.h97 *98 *-------------------------------------------------------------------------99 */100#ifndef LATCH_H101#define LATCH_H102 103#include <signal.h>104 105/*106 * Latch structure should be treated as opaque and only accessed through107 * the public functions. It is defined here to allow embedding Latches as108 * part of bigger structs.109 */110typedef struct Latch111{112	sig_atomic_t is_set;113	sig_atomic_t maybe_sleeping;114	bool		is_shared;115	int			owner_pid;116#ifdef WIN32117	HANDLE		event;118#endif119} Latch;120 121/*122 * Bitmasks for events that may wake-up WaitLatch(), WaitLatchOrSocket(), or123 * WaitEventSetWait().124 */125#define WL_LATCH_SET		 (1 << 0)126#define WL_SOCKET_READABLE	 (1 << 1)127#define WL_SOCKET_WRITEABLE  (1 << 2)128#define WL_TIMEOUT			 (1 << 3)	/* not for WaitEventSetWait() */129#define WL_POSTMASTER_DEATH  (1 << 4)130#define WL_EXIT_ON_PM_DEATH	 (1 << 5)131#ifdef WIN32132#define WL_SOCKET_CONNECTED  (1 << 6)133#else134/* avoid having to deal with case on platforms not requiring it */135#define WL_SOCKET_CONNECTED  WL_SOCKET_WRITEABLE136#endif137#define WL_SOCKET_CLOSED 	 (1 << 7)138#ifdef WIN32139#define WL_SOCKET_ACCEPT	 (1 << 8)140#else141/* avoid having to deal with case on platforms not requiring it */142#define WL_SOCKET_ACCEPT	WL_SOCKET_READABLE143#endif144#define WL_SOCKET_MASK		(WL_SOCKET_READABLE | \145							 WL_SOCKET_WRITEABLE | \146							 WL_SOCKET_CONNECTED | \147							 WL_SOCKET_ACCEPT | \148							 WL_SOCKET_CLOSED)149 150typedef struct WaitEvent151{152	int			pos;			/* position in the event data structure */153	uint32		events;			/* triggered events */154	pgsocket	fd;				/* socket fd associated with event */155	void	   *user_data;		/* pointer provided in AddWaitEventToSet */156#ifdef WIN32157	bool		reset;			/* Is reset of the event required? */158#endif159} WaitEvent;160 161/* forward declaration to avoid exposing latch.c implementation details */162typedef struct WaitEventSet WaitEventSet;163 164/*165 * prototypes for functions in latch.c166 */167extern void InitializeLatchSupport(void);168extern void InitLatch(Latch *latch);169extern void InitSharedLatch(Latch *latch);170extern void OwnLatch(Latch *latch);171extern void DisownLatch(Latch *latch);172extern void SetLatch(Latch *latch);173extern void ResetLatch(Latch *latch);174extern void ShutdownLatchSupport(void);175 176extern WaitEventSet *CreateWaitEventSet(MemoryContext context, int nevents);177extern void FreeWaitEventSet(WaitEventSet *set);178extern void FreeWaitEventSetAfterFork(WaitEventSet *set);179extern int	AddWaitEventToSet(WaitEventSet *set, uint32 events, pgsocket fd,180							  Latch *latch, void *user_data);181extern void ModifyWaitEvent(WaitEventSet *set, int pos, uint32 events, Latch *latch);182 183extern int	WaitEventSetWait(WaitEventSet *set, long timeout,184							 WaitEvent *occurred_events, int nevents,185							 uint32 wait_event_info);186extern int	WaitLatch(Latch *latch, int wakeEvents, long timeout,187					  uint32 wait_event_info);188extern int	WaitLatchOrSocket(Latch *latch, int wakeEvents,189							  pgsocket sock, long timeout, uint32 wait_event_info);190extern void InitializeLatchWaitSet(void);191extern int	GetNumRegisteredWaitEvents(WaitEventSet *set);192extern bool WaitEventSetCanReportClosed(void);193 194#endif							/* LATCH_H */195