1 /*-------------------------------------------------------------------------
4 * Routines for interprocess latches
6 * A latch is a boolean variable, with operations that let processes sleep
7 * until it is set. A latch can be set from another process, or a signal
8 * handler within the same process.
10 * The latch interface is a reliable replacement for the common pattern of
11 * using pg_usleep() or select() to wait until a signal arrives, where the
12 * signal handler sets a flag variable. Because on some platforms an
13 * incoming signal doesn't interrupt sleep, and even on platforms where it
14 * does there is a race condition if the signal arrives just before
15 * entering the sleep, the common pattern must periodically wake up and
16 * poll the flag variable. The pselect() system call was invented to solve
17 * this problem, but it is not portable enough. Latches are designed to
18 * overcome these limitations, allowing you to sleep without polling and
19 * ensuring quick response to signals from other processes.
21 * There are two kinds of latches: local and shared. A local latch is
22 * 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 calling
24 * SetLatch in the signal handler. A shared latch resides in shared memory,
25 * and must be initialized at postmaster startup by InitSharedLatch. Before
26 * a shared latch can be waited on, it must be associated with a process
27 * with OwnLatch. Only the process owning the latch can wait on it, but any
30 * There are three basic operations on a latch:
32 * SetLatch - Sets the latch
33 * ResetLatch - Clears the latch, allowing it to be set again
34 * WaitLatch - Waits for the latch to become set
36 * WaitLatch includes a provision for timeouts (which should be avoided
37 * when possible, as they incur extra overhead) and a provision for
38 * postmaster child processes to wake up immediately on postmaster death.
39 * See unix_latch.c for detailed specifications for the exported functions.
41 * The correct pattern to wait for event(s) is:
51 * It's important to reset the latch *before* checking if there's work to
52 * do. Otherwise, if someone sets the latch between the check and the
53 * ResetLatch call, you will miss it and Wait will incorrectly block.
55 * To wake up the waiter, you must first set a global flag or something
56 * else that the wait loop tests in the "if (work to do)" part, and call
57 * SetLatch *after* that. SetLatch is designed to return quickly if the
58 * latch is already set.
60 * On some platforms, signals will not interrupt the latch wait primitive
61 * by themselves. Therefore, it is critical that any signal handler that
62 * is meant to terminate a WaitLatch wait calls SetLatch.
64 * Note that use of the process latch (PGPROC.procLatch) is generally better
65 * than an ad-hoc shared latch for signaling auxiliary processes. This is
66 * because generic signal handlers will call SetLatch on the process latch
67 * only, so using any latch other than the process latch effectively precludes
68 * use of any generic handler.
71 * Portions Copyright (c) 1996-2015, PostgreSQL Global Development Group
72 * Portions Copyright (c) 1994, Regents of the University of California
74 * src/include/storage/latch.h
76 *-------------------------------------------------------------------------
84 * Latch structure should be treated as opaque and only accessed through
85 * the public functions. It is defined here to allow embedding Latches as
86 * part of bigger structs.
98 /* Bitmasks for events that may wake-up WaitLatch() clients */
99 #define WL_LATCH_SET (1 << 0)
100 #define WL_SOCKET_READABLE (1 << 1)
101 #define WL_SOCKET_WRITEABLE (1 << 2)
102 #define WL_TIMEOUT (1 << 3)
103 #define WL_POSTMASTER_DEATH (1 << 4)
106 * prototypes for functions in latch.c
108 extern void InitializeLatchSupport(void);
109 extern void InitLatch(volatile Latch *latch);
110 extern void InitSharedLatch(volatile Latch *latch);
111 extern void OwnLatch(volatile Latch *latch);
112 extern void DisownLatch(volatile Latch *latch);
113 extern int WaitLatch(volatile Latch *latch, int wakeEvents, long timeout);
114 extern int WaitLatchOrSocket(volatile Latch *latch, int wakeEvents,
115 pgsocket sock, long timeout);
116 extern void SetLatch(volatile Latch *latch);
117 extern void ResetLatch(volatile Latch *latch);
119 /* beware of memory ordering issues if you use this macro! */
120 #define TestLatch(latch) (((volatile Latch *) (latch))->is_set)
123 * Unix implementation uses SIGUSR1 for inter-process signaling.
124 * Win32 doesn't need this.
127 extern void latch_sigusr1_handler(void);
129 #define latch_sigusr1_handler() ((void) 0)