1/*-------------------------------------------------------------------------
4 * POSTGRES shared cache invalidation data manager.
6 * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
7 * Portions Copyright (c) 1994, Regents of the University of California
11 * src/backend/storage/ipc/sinvaladt.c
13 *-------------------------------------------------------------------------
30 * Conceptually, the shared cache invalidation messages are stored in an
31 * infinite array, where maxMsgNum is the next array subscript to store a
32 * submitted message in, minMsgNum is the smallest array subscript containing
33 * a message not yet read by all backends, and we always have maxMsgNum >=
34 * minMsgNum. (They are equal when there are no messages pending.) For each
35 * active backend, there is a nextMsgNum pointer indicating the next message it
36 * needs to read; we have maxMsgNum >= nextMsgNum >= minMsgNum for every
39 * (In the current implementation, minMsgNum is a lower bound for the
40 * per-process nextMsgNum values, but it isn't rigorously kept equal to the
41 * smallest nextMsgNum --- it may lag behind. We only update it when
42 * SICleanupQueue is called, and we try not to do that often.)
44 * In reality, the messages are stored in a circular buffer of MAXNUMMESSAGES
45 * entries. We translate MsgNum values into circular-buffer indexes by
46 * computing MsgNum % MAXNUMMESSAGES (this should be fast as long as
47 * MAXNUMMESSAGES is a constant and a power of 2). As long as maxMsgNum
48 * doesn't exceed minMsgNum by more than MAXNUMMESSAGES, we have enough space
49 * in the buffer. If the buffer does overflow, we recover by setting the
50 * "reset" flag for each backend that has fallen too far behind. A backend
51 * that is in "reset" state is ignored while determining minMsgNum. When
52 * it does finally attempt to receive inval messages, it must discard all
53 * its invalidatable state, since it won't know what it missed.
55 * To reduce the probability of needing resets, we send a "catchup" interrupt
56 * to any backend that seems to be falling unreasonably far behind. The
57 * normal behavior is that at most one such interrupt is in flight at a time;
58 * when a backend completes processing a catchup interrupt, it executes
59 * SICleanupQueue, which will signal the next-furthest-behind backend if
60 * needed. This avoids undue contention from multiple backends all trying
61 * to catch up at once. However, the furthest-back backend might be stuck
62 * in a state where it can't catch up. Eventually it will get reset, so it
63 * won't cause any more problems for anyone but itself. But we don't want
64 * to find that a bunch of other backends are now too close to the reset
65 * threshold to be saved. So SICleanupQueue is designed to occasionally
66 * send extra catchup interrupts as the queue gets fuller, to backends that
67 * are far behind and haven't gotten one yet. As long as there aren't a lot
68 * of "stuck" backends, we won't need a lot of extra interrupts, since ones
69 * that aren't stuck will propagate their interrupts to the next guy.
71 * We would have problems if the MsgNum values overflow an integer, so
72 * whenever minMsgNum exceeds MSGNUMWRAPAROUND, we subtract MSGNUMWRAPAROUND
73 * from all the MsgNum variables simultaneously. MSGNUMWRAPAROUND can be
74 * large so that we don't need to do this often. It must be a multiple of
75 * MAXNUMMESSAGES so that the existing circular-buffer entries don't need
76 * to be moved when we do it.
78 * Access to the shared sinval array is protected by two locks, SInvalReadLock
79 * and SInvalWriteLock. Readers take SInvalReadLock in shared mode; this
80 * authorizes them to modify their own ProcState but not to modify or even
81 * look at anyone else's. When we need to perform array-wide updates,
82 * such as in SICleanupQueue, we take SInvalReadLock in exclusive mode to
83 * lock out all readers. Writers take SInvalWriteLock (always in exclusive
84 * mode) to serialize adding messages to the queue. Note that a writer
85 * can operate in parallel with one or more readers, because the writer
86 * has no need to touch anyone's ProcState, except in the infrequent cases
87 * when SICleanupQueue is needed. The only point of overlap is that
88 * the writer wants to change maxMsgNum while readers need to read it.
89 * We deal with that by having a spinlock that readers must take for just
90 * long enough to read maxMsgNum, while writers take it for just long enough
91 * to write maxMsgNum. (The exact rule is that you need the spinlock to
92 * read maxMsgNum if you are not holding SInvalWriteLock, and you need the
93 * spinlock to write maxMsgNum unless you are holding both locks.)
95 * Note: since maxMsgNum is an int and hence presumably atomically readable/
96 * writable, the spinlock might seem unnecessary. The reason it is needed
97 * is to provide a memory barrier: we need to be sure that messages written
98 * to the array are actually there before maxMsgNum is increased, and that
99 * readers will see that data after fetching maxMsgNum. Multiprocessors
100 * that have weak memory-ordering guarantees can fail without the memory
101 * barrier instructions that are included in the spinlock sequences.
106 * Configurable parameters.
108 * MAXNUMMESSAGES: max number of shared-inval messages we can buffer.
109 * Must be a power of 2 for speed.
111 * MSGNUMWRAPAROUND: how often to reduce MsgNum variables to avoid overflow.
112 * Must be a multiple of MAXNUMMESSAGES. Should be large.
114 * CLEANUP_MIN: the minimum number of messages that must be in the buffer
115 * before we bother to call SICleanupQueue.
117 * CLEANUP_QUANTUM: how often (in messages) to call SICleanupQueue once
118 * we exceed CLEANUP_MIN. Should be a power of 2 for speed.
120 * SIG_THRESHOLD: the minimum number of messages a backend must have fallen
121 * behind before we'll send it PROCSIG_CATCHUP_INTERRUPT.
123 * WRITE_QUANTUM: the max number of messages to push into the buffer per
124 * iteration of SIInsertDataEntries. Noncritical but should be less than
125 * CLEANUP_QUANTUM, because we only consider calling SICleanupQueue once
129 #define MAXNUMMESSAGES 4096
130 #define MSGNUMWRAPAROUND (MAXNUMMESSAGES * 262144)
131 #define CLEANUP_MIN (MAXNUMMESSAGES / 2)
132 #define CLEANUP_QUANTUM (MAXNUMMESSAGES / 16)
133 #define SIG_THRESHOLD (MAXNUMMESSAGES / 2)
134 #define WRITE_QUANTUM 64
136/* Per-backend state in shared invalidation structure */
139 /* procPid is zero in an inactive ProcState array entry. */
140 pid_t
procPid;
/* PID of backend, for signaling */
141 /* nextMsgNum is meaningless if procPid == 0 or resetState is true. */
144 bool signaled;
/* backend has been sent catchup signal */
148 * Backend only sends invalidations, never receives them. This only makes
149 * sense for Startup process during recovery because it doesn't maintain a
150 * relcache, yet it fires inval messages to allow query backends to see
153 bool sendOnly;
/* backend only sends, never receives */
156 * Next LocalTransactionId to use for each idle backend slot. We keep
157 * this here because it is indexed by ProcNumber and it is convenient to
158 * copy the value to and from local memory when MyProcNumber is set. It's
159 * meaningless in an active ProcState entry.
164/* Shared cache invalidation memory segment */
168 * General state information
177 * Circular buffer holding shared-inval messages
182 * Per-backend invalidation state info.
184 * 'procState' has NumProcStateSlots entries, and is indexed by pgprocno.
185 * 'numProcs' is the number of slots currently in use, and 'pgprocnos' is
186 * a dense array of their indexes, to speed up scanning all in-use slots.
188 * 'pgprocnos' is largely redundant with ProcArrayStruct->pgprocnos, but
189 * having our separate copy avoids contention on ProcArrayLock, and allows
190 * us to track only the processes that participate in shared cache
199 * We reserve a slot for each possible ProcNumber, plus one for each
200 * possible auxiliary process type. (This scheme assumes there is not
201 * more than one of any auxiliary process type at a time, except for
204 #define NumProcStateSlots (MaxBackends + NUM_AUXILIARY_PROCS)
215 * SharedInvalShmemSize --- return shared-memory space needed
222 size = offsetof(
SISeg, procState);
230 * SharedInvalShmemInit
231 * Create and initialize the SI message buffer
239 /* Allocate space in shared memory */
245 /* Clear message counters, save size of procState array, init spinlock */
251 /* The buffer[] array is initially all unused, so we need not fill it */
253 /* Mark all backends inactive, and initialize nextLXID */
268 * SharedInvalBackendInit
269 * Initialize a new backend to operate on the sinval buffer
281 elog(
PANIC,
"unexpected MyProcNumber %d in SharedInvalBackendInit (max %d)",
286 * This can run in parallel with read operations, but not with write
287 * operations, since SIInsertDataEntries relies on the pgprocnos array to
288 * set hasMessages appropriately.
296 elog(
ERROR,
"sinval slot for backend %d is already in use by process %d",
302 /* Fetch next local transaction ID into local memory */
305 /* mark myself active, with all extant messages already read */
315 /* register exit routine to mark my entry inactive at exit */
320 * CleanupInvalidationState
321 * Mark the current backend as no longer active.
323 * This function is called via on_shmem_exit() during backend shutdown.
325 * arg is really of type "SISeg*".
340 /* Update next local transaction ID for next holder of this proc number */
343 /* Mark myself inactive */
359 elog(
PANIC,
"could not find entry in sinval array");
366 * SIInsertDataEntries
367 * Add new invalidation message(s) to the buffer.
375 * N can be arbitrarily large. We divide the work into groups of no more
376 * than WRITE_QUANTUM messages, to be sure that we don't hold the lock for
377 * an unreasonably long time. (This is not so much because we care about
378 * letting in other writers, as that some just-caught-up backend might be
379 * trying to do SICleanupQueue to pass on its signal, and we don't want it
380 * to have to wait a long time.) Also, we need to consider calling
381 * SICleanupQueue every so often.
395 * If the buffer is full, we *must* acquire some space. Clean the
396 * queue and reset anyone who is preventing space from being freed.
397 * Otherwise, clean the queue only when it's exceeded the next
398 * fullness threshold. We have to loop and recheck the buffer state
399 * after any call of SICleanupQueue.
412 * Insert new message(s) into proper slot of circular buffer
415 while (nthistime-- > 0)
421 /* Update current value of maxMsgNum using spinlock */
427 * Now that the maxMsgNum change is globally visible, we give everyone
428 * a swift kick to make sure they read the newly added messages.
429 * Releasing SInvalWriteLock will enforce a full memory barrier, so
430 * these (unlocked) changes will be committed to memory before we exit
446 * get next SI message(s) for current backend, if there are any
448 * Possible return values:
449 * 0: no SI message available
450 * n>0: next n SI messages have been extracted into data[]
451 * -1: SI reset message extracted
453 * If the return value is less than the array size "datasize", the caller
454 * can assume that there are no more SI messages after the one(s) returned.
455 * Otherwise, another call is needed to collect more messages.
457 * NB: this can run in parallel with other instances of SIGetDataEntries
458 * executing on behalf of other backends, since each instance will modify only
459 * fields of its own backend's ProcState, and no instance will look at fields
460 * of other backends' ProcStates. We express this by grabbing SInvalReadLock
461 * in shared mode. Note that this is not exactly the normal (read-only)
462 * interpretation of a shared lock! Look closely at the interactions before
463 * allowing SInvalReadLock to be grabbed in shared mode for any other reason!
465 * NB: this can also run in parallel with SIInsertDataEntries. It is not
466 * guaranteed that we will return any messages added after the routine is
469 * Note: we assume that "datasize" is not so large that it might be important
470 * to break our hold on SInvalReadLock into segments.
484 * Before starting to take locks, do a quick, unlocked test to see whether
485 * there can possibly be anything to read. On a multiprocessor system,
486 * it's possible that this load could migrate backwards and occur before
487 * we actually enter this function, so we might miss a sinval message that
488 * was just added by some other processor. But they can't migrate
489 * backwards over a preceding lock acquisition, so it should be OK. If we
490 * haven't acquired a lock preventing against further relevant
491 * invalidations, any such occurrence is not much different than if the
492 * invalidation had arrived slightly later in the first place.
500 * We must reset hasMessages before determining how many messages we're
501 * going to read. That way, if new messages arrive after we have
502 * determined how many we're reading, the flag will get reset and we'll
503 * notice those messages part-way through.
505 * Note that, if we don't end up reading all of the messages, we had
506 * better be certain to reset this flag before exiting!
510 /* Fetch current value of maxMsgNum using spinlock */
518 * Force reset. We can say we have dealt with any messages added
519 * since the reset, as well; and that means we should clear the
520 * signaled flag, too.
530 * Retrieve messages and advance backend's counter, until data array is
531 * full or there are no more messages.
533 * There may be other backends that haven't read the message(s), so we
534 * cannot delete them here. SICleanupQueue() will eventually remove them
538 while (n < datasize && stateP->nextMsgNum < max)
545 * If we have caught up completely, reset our "signaled" flag so that
546 * we'll get another signal if we fall behind again.
548 * If we haven't caught up completely, reset the hasMessages flag so that
549 * we see the remaining messages next time.
562 * Remove messages that have been consumed by all active backends
564 * callerHasWriteLock is true if caller is holding SInvalWriteLock.
565 * minFree is the minimum number of message slots to make free.
567 * Possible side effects of this routine include marking one or more
568 * backends as "reset" in the array, and sending PROCSIG_CATCHUP_INTERRUPT
569 * to some backend that seems to be getting too far behind. We signal at
570 * most one backend at a time, for reasons explained at the top of the file.
572 * Caution: because we transiently release write lock when we have to signal
573 * some other backend, it is NOT guaranteed that there are still minFree
574 * free message slots at exit. Caller must recheck and perhaps retry.
587 /* Lock out all writers and readers */
588 if (!callerHasWriteLock)
593 * Recompute minMsgNum = minimum of all backends' nextMsgNum, identify the
594 * furthest-back backend that needs signaling (if any), and reset any
595 * backends that are too far back. Note that because we ignore sendOnly
596 * backends here it is possible for them to keep sending messages without
597 * a problem even when they are the only active backend.
608 /* Ignore if already in reset state */
614 * If we must free some space and this backend is preventing it, force
615 * him into reset state and then ignore until he catches up.
620 /* no point in signaling him ... */
624 /* Track the global minimum nextMsgNum */
628 /* Also see who's furthest back of the unsignaled backends */
629 if (n < minsig && !stateP->signaled)
638 * When minMsgNum gets really large, decrement all message counters so as
639 * to forestall overflow of the counters. This happens seldom enough that
640 * folding it into the previous loop would be a loser.
651 * Determine how many messages are still in the queue, and set the
652 * threshold at which we should repeat SICleanupQueue().
661 * Lastly, signal anyone who needs a catchup interrupt. Since
662 * SendProcSignal() might not be fast, we don't want to hold locks while
667 pid_t his_pid = needSig->
procPid;
673 elog(
DEBUG4,
"sending sinval catchup signal to PID %d", (
int) his_pid);
675 if (callerHasWriteLock)
681 if (!callerHasWriteLock)
688 * GetNextLocalTransactionId --- allocate a new LocalTransactionId
690 * We split VirtualTransactionIds into two parts so that it is possible
691 * to allocate a new one without any contention for shared memory, except
692 * for a bit of additional overhead during backend startup/shutdown.
693 * The high-order part of a VirtualTransactionId is a ProcNumber, and the
694 * low-order part is a LocalTransactionId, which we assign from a local
695 * counter. To avoid the risk of a VirtualTransactionId being reused
696 * within a short interval, successive procs occupying the same PGPROC slot
697 * should use a consecutive sequence of local IDs, which is implemented
698 * by copying nextLocalTransactionId as seen above.
705 /* loop to avoid returning InvalidLocalTransactionId at wraparound */
#define FLEXIBLE_ARRAY_MEMBER
uint32 LocalTransactionId
Assert(PointerIsAligned(start, uint64))
void on_shmem_exit(pg_on_exit_callback function, Datum arg)
#define InvalidLocalTransactionId
#define LocalTransactionIdIsValid(lxid)
bool LWLockAcquire(LWLock *lock, LWLockMode mode)
void LWLockRelease(LWLock *lock)
static Datum PointerGetDatum(const void *X)
static Pointer DatumGetPointer(Datum X)
int SendProcSignal(pid_t pid, ProcSignalReason reason, ProcNumber procNumber)
@ PROCSIG_CATCHUP_INTERRUPT
Size add_size(Size s1, Size s2)
Size mul_size(Size s1, Size s2)
void * ShmemInitStruct(const char *name, Size size, bool *foundPtr)
struct ProcState ProcState
static SISeg * shmInvalBuffer
void SICleanupQueue(bool callerHasWriteLock, int minFree)
#define NumProcStateSlots
static void CleanupInvalidationState(int status, Datum arg)
Size SharedInvalShmemSize(void)
void SharedInvalBackendInit(bool sendOnly)
int SIGetDataEntries(SharedInvalidationMessage *data, int datasize)
void SharedInvalShmemInit(void)
void SIInsertDataEntries(const SharedInvalidationMessage *data, int n)
LocalTransactionId GetNextLocalTransactionId(void)
static LocalTransactionId nextLocalTransactionId
#define SpinLockInit(lock)
#define SpinLockRelease(lock)
#define SpinLockAcquire(lock)
LocalTransactionId nextLXID
SharedInvalidationMessage buffer[MAXNUMMESSAGES]
ProcState procState[FLEXIBLE_ARRAY_MEMBER]