PostgreSQL Source Code  git master
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros
latch.h
Go to the documentation of this file.
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-2017, 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;
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 #ifdef WIN32
130 #define WL_SOCKET_CONNECTED (1 << 5)
131 #else
132 /* avoid having to to deal with case on platforms not requiring it */
133 #define WL_SOCKET_CONNECTED WL_SOCKET_WRITEABLE
134 #endif
135 
136 #define WL_SOCKET_MASK (WL_SOCKET_READABLE | \
137  WL_SOCKET_WRITEABLE | \
138  WL_SOCKET_CONNECTED)
139 
140 typedef struct WaitEvent
141 {
142  int pos; /* position in the event data structure */
143  uint32 events; /* triggered events */
144  pgsocket fd; /* socket fd associated with event */
145  void *user_data; /* pointer provided in AddWaitEventToSet */
146 #ifdef WIN32
147  bool reset; /* Is reset of the event required? */
148 #endif
149 } WaitEvent;
150 
151 /* forward declaration to avoid exposing latch.c implementation details */
152 typedef struct WaitEventSet WaitEventSet;
153 
154 /*
155  * prototypes for functions in latch.c
156  */
157 extern void InitializeLatchSupport(void);
158 extern void InitLatch(volatile Latch *latch);
159 extern void InitSharedLatch(volatile Latch *latch);
160 extern void OwnLatch(volatile Latch *latch);
161 extern void DisownLatch(volatile Latch *latch);
162 extern void SetLatch(volatile Latch *latch);
163 extern void ResetLatch(volatile Latch *latch);
164 
166 extern void FreeWaitEventSet(WaitEventSet *set);
168  Latch *latch, void *user_data);
169 extern void ModifyWaitEvent(WaitEventSet *set, int pos, uint32 events, Latch *latch);
170 
171 extern int WaitEventSetWait(WaitEventSet *set, long timeout,
172  WaitEvent *occurred_events, int nevents,
173  uint32 wait_event_info);
174 extern int WaitLatch(volatile Latch *latch, int wakeEvents, long timeout,
175  uint32 wait_event_info);
176 extern int WaitLatchOrSocket(volatile Latch *latch, int wakeEvents,
177  pgsocket sock, long timeout, uint32 wait_event_info);
178 
179 /*
180  * Unix implementation uses SIGUSR1 for inter-process signaling.
181  * Win32 doesn't need this.
182  */
183 #ifndef WIN32
184 extern void latch_sigusr1_handler(void);
185 #else
186 #define latch_sigusr1_handler() ((void) 0)
187 #endif
188 
189 #endif /* LATCH_H */
pgsocket fd
Definition: latch.h:144
void DisownLatch(volatile Latch *latch)
Definition: latch.c:308
int pos
Definition: latch.h:142
WaitEventSet * CreateWaitEventSet(MemoryContext context, int nevents)
Definition: latch.c:520
int WaitLatchOrSocket(volatile Latch *latch, int wakeEvents, pgsocket sock, long timeout, uint32 wait_event_info)
Definition: latch.c:356
bool is_shared
Definition: latch.h:113
int WaitEventSetWait(WaitEventSet *set, long timeout, WaitEvent *occurred_events, int nevents, uint32 wait_event_info)
Definition: latch.c:921
void ModifyWaitEvent(WaitEventSet *set, int pos, uint32 events, Latch *latch)
Definition: latch.c:736
static int fd(const char *x, int i)
Definition: preproc-init.c:105
void FreeWaitEventSet(WaitEventSet *set)
Definition: latch.c:607
void latch_sigusr1_handler(void)
Definition: latch.c:1473
int AddWaitEventToSet(WaitEventSet *set, uint32 events, pgsocket fd, Latch *latch, void *user_data)
Definition: latch.c:666
struct Latch Latch
void InitLatch(volatile Latch *latch)
Definition: latch.c:220
uint32 events
Definition: latch.h:143
Definition: latch.h:110
void OwnLatch(volatile Latch *latch)
Definition: latch.c:288
int WaitLatch(volatile Latch *latch, int wakeEvents, long timeout, uint32 wait_event_info)
Definition: latch.c:336
unsigned int uint32
Definition: c.h:268
int pgsocket
Definition: port.h:22
void InitSharedLatch(volatile Latch *latch)
Definition: latch.c:252
int nevents
Definition: latch.c:77
WaitEvent * events
Definition: latch.c:84
void SetLatch(volatile Latch *latch)
Definition: latch.c:414
void * user_data
Definition: latch.h:145
struct WaitEvent WaitEvent
int owner_pid
Definition: latch.h:114
sig_atomic_t is_set
Definition: latch.h:112
void ResetLatch(volatile Latch *latch)
Definition: latch.c:497
void InitializeLatchSupport(void)
Definition: latch.c:147
Latch * latch
Definition: latch.c:92