util/X86MAC64/include/postgresql/server/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 unix_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  * 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.
  59  *
  60  * Presently, when using a shared latch for interprocess signalling, the
  61  * flag variable(s) set by senders and inspected by the wait loop must
  62  * be protected by spinlocks or LWLocks, else it is possible to miss events
  63  * on machines with weak memory ordering (such as PPC).  This restriction
  64  * will be lifted in future by inserting suitable memory barriers into
  65  * SetLatch and ResetLatch.
  66  *
  67  * On some platforms, signals will not interrupt the latch wait primitive
  68  * by themselves.  Therefore, it is critical that any signal handler that
  69  * is meant to terminate a WaitLatch wait calls SetLatch.
  70  *
  71  * Note that use of the process latch (PGPROC.procLatch) is generally better
  72  * than an ad-hoc shared latch for signaling auxiliary processes.  This is
  73  * because generic signal handlers will call SetLatch on the process latch
  74  * only, so using any latch other than the process latch effectively precludes
  75  * use of any generic handler.
  76  *
  77  *
  78  * Portions Copyright (c) 1996-2014, PostgreSQL Global Development Group
  79  * Portions Copyright (c) 1994, Regents of the University of California
  80  *
  81  * src/include/storage/latch.h
  82  *
  83  *-------------------------------------------------------------------------
  84  */
  85 #ifndef LATCH_H
  86 #define LATCH_H
  87
  88 #include <signal.h>
  89
  90 /*
  91  * Latch structure should be treated as opaque and only accessed through
  92  * the public functions. It is defined here to allow embedding Latches as
  93  * part of bigger structs.
  94  */
  95 typedef struct
  96 {
  97         sig_atomic_t is_set;
  98         bool            is_shared;
  99         int                     owner_pid;
 100 #ifdef WIN32
 101         HANDLE          event;
 102 #endif
 103 } Latch;
 104
 105 /* Bitmasks for events that may wake-up WaitLatch() clients */
 106 #define WL_LATCH_SET             (1 << 0)
 107 #define WL_SOCKET_READABLE       (1 << 1)
 108 #define WL_SOCKET_WRITEABLE  (1 << 2)
 109 #define WL_TIMEOUT                       (1 << 3)
 110 #define WL_POSTMASTER_DEATH  (1 << 4)
 111
 112 /*
 113  * prototypes for functions in latch.c
 114  */
 115 extern void InitializeLatchSupport(void);
 116 extern void InitLatch(volatile Latch *latch);
 117 extern void InitSharedLatch(volatile Latch *latch);
 118 extern void OwnLatch(volatile Latch *latch);
 119 extern void DisownLatch(volatile Latch *latch);
 120 extern int      WaitLatch(volatile Latch *latch, int wakeEvents, long timeout);
 121 extern int WaitLatchOrSocket(volatile Latch *latch, int wakeEvents,
 122                                   pgsocket sock, long timeout);
 123 extern void SetLatch(volatile Latch *latch);
 124 extern void ResetLatch(volatile Latch *latch);
 125
 126 /* beware of memory ordering issues if you use this macro! */
 127 #define TestLatch(latch) (((volatile Latch *) (latch))->is_set)
 128
 129 /*
 130  * Unix implementation uses SIGUSR1 for inter-process signaling.
 131  * Win32 doesn't need this.
 132  */
 133 #ifndef WIN32
 134 extern void latch_sigusr1_handler(void);
 135 #else
 136 #define latch_sigusr1_handler()  ((void) 0)
 137 #endif
 138
 139 #endif   /* LATCH_H */