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-2019, 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 */
110typedef 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#define WL_EXIT_ON_PM_DEATH (1 << 5)
130#ifdef WIN32
131#define WL_SOCKET_CONNECTED (1 << 6)
132#else
133/* avoid having to deal with case on platforms not requiring it */
134#define WL_SOCKET_CONNECTED WL_SOCKET_WRITEABLE
135#endif
136
137#define WL_SOCKET_MASK (WL_SOCKET_READABLE | \
138 WL_SOCKET_WRITEABLE | \
139 WL_SOCKET_CONNECTED)
140
141typedef struct WaitEvent
142{
143 int pos; /* position in the event data structure */
144 uint32 events; /* triggered events */
145 pgsocket fd; /* socket fd associated with event */
146 void *user_data; /* pointer provided in AddWaitEventToSet */
147#ifdef WIN32
148 bool reset; /* Is reset of the event required? */
149#endif
150} WaitEvent;
151
152/* forward declaration to avoid exposing latch.c implementation details */
153typedef struct WaitEventSet WaitEventSet;
154
155/*
156 * prototypes for functions in latch.c
157 */
158extern void InitializeLatchSupport(void);
159extern void InitLatch(Latch *latch);
160extern void InitSharedLatch(Latch *latch);
161extern void OwnLatch(Latch *latch);
162extern void DisownLatch(Latch *latch);
163extern void SetLatch(Latch *latch);
164extern void ResetLatch(Latch *latch);
165
166extern WaitEventSet *CreateWaitEventSet(MemoryContext context, int nevents);
167extern void FreeWaitEventSet(WaitEventSet *set);
168extern int AddWaitEventToSet(WaitEventSet *set, uint32 events, pgsocket fd,
169 Latch *latch, void *user_data);
170extern void ModifyWaitEvent(WaitEventSet *set, int pos, uint32 events, Latch *latch);
171
172extern int WaitEventSetWait(WaitEventSet *set, long timeout,
173 WaitEvent *occurred_events, int nevents,
174 uint32 wait_event_info);
175extern int WaitLatch(Latch *latch, int wakeEvents, long timeout,
176 uint32 wait_event_info);
177extern int WaitLatchOrSocket(Latch *latch, int wakeEvents,
178 pgsocket sock, long timeout, uint32 wait_event_info);
179
180/*
181 * Unix implementation uses SIGUSR1 for inter-process signaling.
182 * Win32 doesn't need this.
183 */
184#ifndef WIN32
185extern void latch_sigusr1_handler(void);
186#else
187#define latch_sigusr1_handler() ((void) 0)
188#endif
189
190#endif /* LATCH_H */
191