1 /*------------------------------------------------------------------------- 2 * 3 * latch.h 4 * Routines for interprocess latches 5 * 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. 9 * 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. 20 * 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 28 * process can set it. 29 * 30 * There are three basic operations on a latch: 31 * 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 35 * 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 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 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. 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 satisfied 61 * WaitLatch(); 62 * ResetLatch(); 63 * } 64 * 65 * This is useful to reduce latch traffic if it's expected that the loop's 66 * 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 after 69 * 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 something 72 * else that the wait loop tests in the "if (work to do)" part, and call 73 * SetLatch *after* that. SetLatch is designed to return quickly if the 74 * latch is already set. 75 * 76 * On some platforms, signals will not interrupt the latch wait primitive 77 * by themselves. Therefore, it is critical that any signal handler that 78 * is meant to terminate a WaitLatch wait calls SetLatch. 79 * 80 * Note that use of the process latch (PGPROC.procLatch) is generally better 81 * than an ad-hoc shared latch for signaling auxiliary processes. This is 82 * because generic signal handlers will call SetLatch on the process latch 83 * only, so using any latch other than the process latch effectively precludes 84 * 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 the 89 * same time. On many platforms using a long lived event set is more 90 * efficient than using WaitLatch or WaitLatchOrSocket. 91 * 92 * 93 * Portions Copyright (c) 1996-2016, PostgreSQL Global Development Group 94 * Portions Copyright (c) 1994, Regents of the University of California 95 * 96 * src/include/storage/latch.h 97 * 98 *------------------------------------------------------------------------- 99 */ 100 #ifndef LATCH_H 101 #define LATCH_H 102 103 #include <signal.h> 104 105 /* 106 * Latch structure should be treated as opaque and only accessed through 107 * the public functions. It is defined here to allow embedding Latches as 108 * part of bigger structs. 109 */ 110 typedef struct Latch 111 { 112 sig_atomic_t is_set; 113 bool is_shared; 114 int owner_pid; 115 #ifdef WIN32 116 HANDLE event; 117 #endif 118 } Latch; 119 120 /* 121 * Bitmasks for events that may wake-up WaitLatch(), WaitLatchOrSocket(), or 122 * WaitEventSetWait(). 123 */ 124 #define WL_LATCH_SET (1 << 0) 125 #define WL_SOCKET_READABLE (1 << 1) 126 #define WL_SOCKET_WRITEABLE (1 << 2) 127 #define WL_TIMEOUT (1 << 3) /* not for WaitEventSetWait() */ 128 #define WL_POSTMASTER_DEATH (1 << 4) 129 130 typedef struct WaitEvent 131 { 132 int pos; /* position in the event data structure */ 133 uint32 events; /* triggered events */ 134 pgsocket fd; /* socket fd associated with event */ 135 void *user_data; /* pointer provided in AddWaitEventToSet */ 136 #ifdef WIN32 137 bool reset; /* Is reset of the event required? */ 138 #endif 139 } WaitEvent; 140 141 /* forward declaration to avoid exposing latch.c implementation details */ 142 typedef struct WaitEventSet WaitEventSet; 143 144 /* 145 * prototypes for functions in latch.c 146 */ 147 extern void InitializeLatchSupport(void); 148 extern void InitLatch(volatile Latch *latch); 149 extern void InitSharedLatch(volatile Latch *latch); 150 extern void OwnLatch(volatile Latch *latch); 151 extern void DisownLatch(volatile Latch *latch); 152 extern void SetLatch(volatile Latch *latch); 153 extern void ResetLatch(volatile Latch *latch); 154 155 extern WaitEventSet *CreateWaitEventSet(MemoryContext context, int nevents); 156 extern void FreeWaitEventSet(WaitEventSet *set); 157 extern int AddWaitEventToSet(WaitEventSet *set, uint32 events, pgsocket fd, 158 Latch *latch, void *user_data); 159 extern void ModifyWaitEvent(WaitEventSet *set, int pos, uint32 events, Latch *latch); 160 161 extern int WaitEventSetWait(WaitEventSet *set, long timeout, WaitEvent *occurred_events, int nevents); 162 extern int WaitLatch(volatile Latch *latch, int wakeEvents, long timeout); 163 extern int WaitLatchOrSocket(volatile Latch *latch, int wakeEvents, 164 pgsocket sock, long timeout); 165 166 /* 167 * Unix implementation uses SIGUSR1 for inter-process signaling. 168 * Win32 doesn't need this. 169 */ 170 #ifndef WIN32 171 extern void latch_sigusr1_handler(void); 172 #else 173 #define latch_sigusr1_handler() ((void) 0) 174 #endif 175 176 #endif /* LATCH_H */ 177