src/include/storage/latch.h

   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-2024, 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 #include "utils/resowner.h"
 106
 107 /*
 108  * Latch structure should be treated as opaque and only accessed through
 109  * the public functions. It is defined here to allow embedding Latches as
 110  * part of bigger structs.
 111  */
 112 typedef struct Latch
 113 {
 114         sig_atomic_t is_set;
 115         sig_atomic_t maybe_sleeping;
 116         bool            is_shared;
 117         int                     owner_pid;
 118 #ifdef WIN32
 119         HANDLE          event;
 120 #endif
 121 } Latch;
 122
 123 /*
 124  * Bitmasks for events that may wake-up WaitLatch(), WaitLatchOrSocket(), or
 125  * WaitEventSetWait().
 126  */
 127 #define WL_LATCH_SET             (1 << 0)
 128 #define WL_SOCKET_READABLE       (1 << 1)
 129 #define WL_SOCKET_WRITEABLE  (1 << 2)
 130 #define WL_TIMEOUT                       (1 << 3)       /* not for WaitEventSetWait() */
 131 #define WL_POSTMASTER_DEATH  (1 << 4)
 132 #define WL_EXIT_ON_PM_DEATH      (1 << 5)
 133 #ifdef WIN32
 134 #define WL_SOCKET_CONNECTED  (1 << 6)
 135 #else
 136 /* avoid having to deal with case on platforms not requiring it */
 137 #define WL_SOCKET_CONNECTED  WL_SOCKET_WRITEABLE
 138 #endif
 139 #define WL_SOCKET_CLOSED         (1 << 7)
 140 #ifdef WIN32
 141 #define WL_SOCKET_ACCEPT         (1 << 8)
 142 #else
 143 /* avoid having to deal with case on platforms not requiring it */
 144 #define WL_SOCKET_ACCEPT        WL_SOCKET_READABLE
 145 #endif
 146 #define WL_SOCKET_MASK          (WL_SOCKET_READABLE | \
 147                                                          WL_SOCKET_WRITEABLE | \
 148                                                          WL_SOCKET_CONNECTED | \
 149                                                          WL_SOCKET_ACCEPT | \
 150                                                          WL_SOCKET_CLOSED)
 151
 152 typedef struct WaitEvent
 153 {
 154         int                     pos;                    /* position in the event data structure */
 155         uint32          events;                 /* triggered events */
 156         pgsocket        fd;                             /* socket fd associated with event */
 157         void       *user_data;          /* pointer provided in AddWaitEventToSet */
 158 #ifdef WIN32
 159         bool            reset;                  /* Is reset of the event required? */
 160 #endif
 161 } WaitEvent;
 162
 163 /* forward declaration to avoid exposing latch.c implementation details */
 164 typedef struct WaitEventSet WaitEventSet;
 165
 166 /*
 167  * prototypes for functions in latch.c
 168  */
 169 extern void InitializeLatchSupport(void);
 170 extern void InitLatch(Latch *latch);
 171 extern void InitSharedLatch(Latch *latch);
 172 extern void OwnLatch(Latch *latch);
 173 extern void DisownLatch(Latch *latch);
 174 extern void SetLatch(Latch *latch);
 175 extern void ResetLatch(Latch *latch);
 176 extern void ShutdownLatchSupport(void);
 177
 178 extern WaitEventSet *CreateWaitEventSet(ResourceOwner resowner, int nevents);
 179 extern void FreeWaitEventSet(WaitEventSet *set);
 180 extern void FreeWaitEventSetAfterFork(WaitEventSet *set);
 181 extern int      AddWaitEventToSet(WaitEventSet *set, uint32 events, pgsocket fd,
 182                                                           Latch *latch, void *user_data);
 183 extern void ModifyWaitEvent(WaitEventSet *set, int pos, uint32 events, Latch *latch);
 184
 185 extern int      WaitEventSetWait(WaitEventSet *set, long timeout,
 186                                                          WaitEvent *occurred_events, int nevents,
 187                                                          uint32 wait_event_info);
 188 extern int      WaitLatch(Latch *latch, int wakeEvents, long timeout,
 189                                           uint32 wait_event_info);
 190 extern int      WaitLatchOrSocket(Latch *latch, int wakeEvents,
 191                                                           pgsocket sock, long timeout, uint32 wait_event_info);
 192 extern void InitializeLatchWaitSet(void);
 193 extern int      GetNumRegisteredWaitEvents(WaitEventSet *set);
 194 extern bool WaitEventSetCanReportClosed(void);
 195
 196 #endif                                                  /* LATCH_H */