| blob | 27ccdf9500fb251632b080679de03ffe57edd6c7 |
1 /*-------------------------------------------------------------------------
2 *
3 * multixact.c
4 * PostgreSQL multi-transaction-log manager
5 *
6 * The pg_multixact manager is a pg_xact-like manager that stores an array of
7 * MultiXactMember for each MultiXactId. It is a fundamental part of the
8 * shared-row-lock implementation. Each MultiXactMember is comprised of a
9 * TransactionId and a set of flag bits. The name is a bit historical:
10 * originally, a MultiXactId consisted of more than one TransactionId (except
11 * in rare corner cases), hence "multi". Nowadays, however, it's perfectly
12 * legitimate to have MultiXactIds that only include a single Xid.
13 *
14 * The meaning of the flag bits is opaque to this module, but they are mostly
15 * used in heapam.c to identify lock modes that each of the member transactions
16 * is holding on any given tuple. This module just contains support to store
17 * and retrieve the arrays.
18 *
19 * We use two SLRU areas, one for storing the offsets at which the data
20 * starts for each MultiXactId in the other one. This trick allows us to
21 * store variable length arrays of TransactionIds. (We could alternatively
22 * use one area containing counts and TransactionIds, with valid MultiXactId
23 * values pointing at slots containing counts; but that way seems less robust
24 * since it would get completely confused if someone inquired about a bogus
25 * MultiXactId that pointed to an intermediate slot containing an XID.)
26 *
27 * XLOG interactions: this module generates a record whenever a new OFFSETs or
28 * MEMBERs page is initialized to zeroes, as well as an
29 * XLOG_MULTIXACT_CREATE_ID record whenever a new MultiXactId is defined.
30 * This module ignores the WAL rule "write xlog before data," because it
31 * suffices that actions recording a MultiXactId in a heap xmax do follow that
32 * rule. The only way for the MXID to be referenced from any data page is for
33 * heap_lock_tuple() or heap_update() to have put it there, and each generates
34 * an XLOG record that must follow ours. The normal LSN interlock between the
35 * data page and that XLOG record will ensure that our XLOG record reaches
36 * disk first. If the SLRU members/offsets data reaches disk sooner than the
37 * XLOG records, we do not care; after recovery, no xmax will refer to it. On
38 * the flip side, to ensure that all referenced entries _do_ reach disk, this
39 * module's XLOG records completely rebuild the data entered since the last
40 * checkpoint. We flush and sync all dirty OFFSETs and MEMBERs pages to disk
41 * before each checkpoint is considered complete.
42 *
43 * Like clog.c, and unlike subtrans.c, we have to preserve state across
44 * crashes and ensure that MXID and offset numbering increases monotonically
45 * across a crash. We do this in the same way as it's done for transaction
46 * IDs: the WAL record is guaranteed to contain evidence of every MXID we
47 * could need to worry about, and we just make sure that at the end of
48 * replay, the next-MXID and next-offset counters are at least as large as
49 * anything we saw during replay.
50 *
51 * We are able to remove segments no longer necessary by carefully tracking
52 * each table's used values: during vacuum, any multixact older than a certain
53 * value is removed; the cutoff value is stored in pg_class. The minimum value
54 * across all tables in each database is stored in pg_database, and the global
55 * minimum across all databases is part of pg_control and is kept in shared
56 * memory. Whenever that minimum is advanced, the SLRUs are truncated.
57 *
58 * When new multixactid values are to be created, care is taken that the
59 * counter does not fall within the wraparound horizon considering the global
60 * minimum value.
61 *
62 * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
63 * Portions Copyright (c) 1994, Regents of the University of California
64 *
65 * src/backend/access/transam/multixact.c
66 *
67 *-------------------------------------------------------------------------
68 */
96 /*
97 * Defines for MultiXactOffset page sizes. A page is the same BLCKSZ as is
98 * used everywhere else in Postgres.
99 *
100 * Note: because MultiXactOffsets are 32 bits and wrap around at 0xFFFFFFFF,
101 * MultiXact page numbering also wraps around at
102 * 0xFFFFFFFF/MULTIXACT_OFFSETS_PER_PAGE, and segment numbering at
103 * 0xFFFFFFFF/MULTIXACT_OFFSETS_PER_PAGE/SLRU_PAGES_PER_SEGMENT. We need
104 * take no explicit notice of that fact in this module, except when comparing
105 * segment and page numbers in TruncateMultiXact (see
106 * MultiXactOffsetPagePrecedes).
107 */
109 /* We need four bytes per offset */
110 #define MULTIXACT_OFFSETS_PER_PAGE (BLCKSZ / sizeof(MultiXactOffset))
114 {
116 }
120 {
122 }
126 {
128 }
130 /*
131 * The situation for members is a bit more complex: we store one byte of
132 * additional flag bits for each TransactionId. To do this without getting
133 * into alignment issues, we store four bytes of flags, and then the
134 * corresponding 4 Xids. Each such 5-word (20-byte) set we call a "group", and
135 * are stored as a whole in pages. Thus, with 8kB BLCKSZ, we keep 409 groups
136 * per page. This wastes 12 bytes per page, but that's OK -- simplicity (and
137 * performance) trumps space efficiency here.
138 *
139 * Note that the "offset" macros work with byte offset, not array indexes, so
140 * arithmetic must be done using "char *" pointers.
141 */
142 /* We need eight bits per xact, so one xact fits in a byte */
143 #define MXACT_MEMBER_BITS_PER_XACT 8
144 #define MXACT_MEMBER_FLAGS_PER_BYTE 1
145 #define MXACT_MEMBER_XACT_BITMASK ((1 << MXACT_MEMBER_BITS_PER_XACT) - 1)
147 /* how many full bytes of flags are there in a group? */
148 #define MULTIXACT_FLAGBYTES_PER_GROUP 4
149 #define MULTIXACT_MEMBERS_PER_MEMBERGROUP \
150 (MULTIXACT_FLAGBYTES_PER_GROUP * MXACT_MEMBER_FLAGS_PER_BYTE)
151 /* size in bytes of a complete group */
152 #define MULTIXACT_MEMBERGROUP_SIZE \
153 (sizeof(TransactionId) * MULTIXACT_MEMBERS_PER_MEMBERGROUP + MULTIXACT_FLAGBYTES_PER_GROUP)
154 #define MULTIXACT_MEMBERGROUPS_PER_PAGE (BLCKSZ / MULTIXACT_MEMBERGROUP_SIZE)
155 #define MULTIXACT_MEMBERS_PER_PAGE \
156 (MULTIXACT_MEMBERGROUPS_PER_PAGE * MULTIXACT_MEMBERS_PER_MEMBERGROUP)
158 /*
159 * Because the number of items per page is not a divisor of the last item
160 * number (member 0xFFFFFFFF), the last segment does not use the maximum number
161 * of pages, and moreover the last used page therein does not use the same
162 * number of items as previous pages. (Another way to say it is that the
163 * 0xFFFFFFFF member is somewhere in the middle of the last page, so the page
164 * has some empty space after that item.)
165 *
166 * This constant is the number of members in the last page of the last segment.
167 */
168 #define MAX_MEMBERS_IN_LAST_MEMBERS_PAGE \
169 ((uint32) ((0xFFFFFFFF % MULTIXACT_MEMBERS_PER_PAGE) + 1))
171 /* page in which a member is to be found */
174 {
176 }
180 {
182 }
184 /* Location (byte offset within page) of flag word for a given member */
187 {
193 }
197 {
202 }
204 /* Location (byte offset within page) of TransactionId of given member */
207 {
211 MULTIXACT_FLAGBYTES_PER_GROUP +
213 }
215 /* Multixact members wraparound thresholds. */
216 #define MULTIXACT_MEMBER_SAFE_THRESHOLD (MaxMultiXactOffset / 2)
217 #define MULTIXACT_MEMBER_DANGER_THRESHOLD \
218 (MaxMultiXactOffset - MaxMultiXactOffset / 4)
222 {
224 }
226 /*
227 * Links to shared-memory data structures for MultiXact control
228 */
232 #define MultiXactOffsetCtl (&MultiXactOffsetCtlData)
233 #define MultiXactMemberCtl (&MultiXactMemberCtlData)
235 /*
236 * MultiXact state shared across all backends. All this state is protected
237 * by MultiXactGenLock. (We also use SLRU bank's lock of MultiXactOffset and
238 * MultiXactMember to guard accesses to the two sets of SLRU buffers. For
239 * concurrency's sake, we avoid holding more than one of these locks at a
240 * time.)
241 */
243 {
244 /* next-to-be-assigned MultiXactId */
245 MultiXactId nextMXact;
247 /* next-to-be-assigned offset */
248 MultiXactOffset nextOffset;
250 /* Have we completed multixact startup? */
253 /*
254 * Oldest multixact that is still potentially referenced by a relation.
255 * Anything older than this should not be consulted. These values are
256 * updated by vacuum.
257 */
258 MultiXactId oldestMultiXactId;
259 Oid oldestMultiXactDB;
261 /*
262 * Oldest multixact offset that is potentially referenced by a multixact
263 * referenced by a relation. We don't always know this value, so there's
264 * a flag here to indicate whether or not we currently do.
265 */
266 MultiXactOffset oldestOffset;
269 /* support for anti-wraparound measures */
270 MultiXactId multiVacLimit;
271 MultiXactId multiWarnLimit;
272 MultiXactId multiStopLimit;
273 MultiXactId multiWrapLimit;
275 /* support for members anti-wraparound measures */
278 /*
279 * This is used to sleep until a multixact offset is written when we want
280 * to create the next one.
281 */
282 ConditionVariable nextoff_cv;
284 /*
285 * Per-backend data starts here. We have two arrays stored in the area
286 * immediately following the MultiXactStateData struct. Each is indexed by
287 * ProcNumber.
288 *
289 * In both arrays, there's a slot for all normal backends
290 * (0..MaxBackends-1) followed by a slot for max_prepared_xacts prepared
291 * transactions.
292 *
293 * OldestMemberMXactId[k] is the oldest MultiXactId each backend's current
294 * transaction(s) could possibly be a member of, or InvalidMultiXactId
295 * when the backend has no live transaction that could possibly be a
296 * member of a MultiXact. Each backend sets its entry to the current
297 * nextMXact counter just before first acquiring a shared lock in a given
298 * transaction, and clears it at transaction end. (This works because only
299 * during or after acquiring a shared lock could an XID possibly become a
300 * member of a MultiXact, and that MultiXact would have to be created
301 * during or after the lock acquisition.)
302 *
303 * OldestVisibleMXactId[k] is the oldest MultiXactId each backend's
304 * current transaction(s) think is potentially live, or InvalidMultiXactId
305 * when not in a transaction or not in a transaction that's paid any
306 * attention to MultiXacts yet. This is computed when first needed in a
307 * given transaction, and cleared at transaction end. We can compute it
308 * as the minimum of the valid OldestMemberMXactId[] entries at the time
309 * we compute it (using nextMXact if none are valid). Each backend is
310 * required not to attempt to access any SLRU data for MultiXactIds older
311 * than its own OldestVisibleMXactId[] setting; this is necessary because
312 * the relevant SLRU data can be concurrently truncated away.
313 *
314 * The oldest valid value among all of the OldestMemberMXactId[] and
315 * OldestVisibleMXactId[] entries is considered by vacuum as the earliest
316 * possible value still having any live member transaction -- OldestMxact.
317 * Any value older than that is typically removed from tuple headers, or
318 * "frozen" via being replaced with a new xmax. VACUUM can sometimes even
319 * remove an individual MultiXact xmax whose value is >= its OldestMxact
320 * cutoff, though typically only when no individual member XID is still
321 * running. See FreezeMultiXactId for full details.
322 *
323 * Whenever VACUUM advances relminmxid, then either its OldestMxact cutoff
324 * or the oldest extant Multi remaining in the table is used as the new
325 * pg_class.relminmxid value (whichever is earlier). The minimum of all
326 * relminmxid values in each database is stored in pg_database.datminmxid.
327 * In turn, the minimum of all of those values is stored in pg_control.
328 * This is used as the truncation point for pg_multixact when unneeded
329 * segments get removed by vac_truncate_clog() during vacuuming.
330 */
334 /*
335 * Size of OldestMemberMXactId and OldestVisibleMXactId arrays.
336 */
337 #define MaxOldestSlot (MaxBackends + max_prepared_xacts)
339 /* Pointers to the state data in shared memory */
345 /*
346 * Definitions for the backend-local MultiXactId cache.
347 *
348 * We use this cache to store known MultiXacts, so we don't need to go to
349 * SLRU areas every time.
350 *
351 * The cache lasts for the duration of a single transaction, the rationale
352 * for this being that most entries will contain our own TransactionId and
353 * so they will be uninteresting by the time our next transaction starts.
354 * (XXX not clear that this is correct --- other members of the MultiXact
355 * could hang around longer than we did. However, it's not clear what a
356 * better policy for flushing old cache entries would be.) FIXME actually
357 * this is plain wrong now that multixact's may contain update Xids.
358 *
359 * We allocate the cache entries in a memory context that is deleted at
360 * transaction end, so we don't need to do retail freeing of entries.
361 */
363 {
364 MultiXactId multi;
366 dlist_node node;
370 #define MAX_CACHE_ENTRIES 256
374 #ifdef MULTIXACT_DEBUG
375 #define debug_elog2(a,b) elog(a,b)
376 #define debug_elog3(a,b,c) elog(a,b,c)
377 #define debug_elog4(a,b,c,d) elog(a,b,c,d)
378 #define debug_elog5(a,b,c,d,e) elog(a,b,c,d,e)
379 #define debug_elog6(a,b,c,d,e,f) elog(a,b,c,d,e,f)
380 #else
381 #define debug_elog2(a,b)
382 #define debug_elog3(a,b,c)
383 #define debug_elog4(a,b,c,d)
384 #define debug_elog5(a,b,c,d,e)
385 #define debug_elog6(a,b,c,d,e,f)
386 #endif
388 /* internal MultiXactId management */
394 /* MultiXact cache management */
403 /* management of SLRU infrastructure */
409 MultiXactOffset offset2);
418 MultiXactId startTruncOff,
419 MultiXactId endTruncOff,
420 MultiXactOffset startTruncMemb,
421 MultiXactOffset endTruncMemb);
424 /*
425 * MultiXactIdCreate
426 * Construct a MultiXactId representing two TransactionIds.
427 *
428 * The two XIDs must be different, or be requesting different statuses.
429 *
430 * NB - we don't worry about our local MultiXactId cache here, because that
431 * is handled by the lower-level routines.
432 */
433 MultiXactId
436 {
437 MultiXactId newMulti;
445 /* MultiXactIdSetOldestMember() must have been called already. */
448 /*
449 * Note: unlike MultiXactIdExpand, we don't bother to check that both XIDs
450 * are still running. In typical usage, xid2 will be our own XID and the
451 * caller just did a check on xid1, so it'd be wasted effort.
452 */
465 }
467 /*
468 * MultiXactIdExpand
469 * Add a TransactionId to a pre-existing MultiXactId.
470 *
471 * If the TransactionId is already a member of the passed MultiXactId with the
472 * same status, just return it as-is.
473 *
474 * Note that we do NOT actually modify the membership of a pre-existing
475 * MultiXactId; instead we create a new one. This is necessary to avoid
476 * a race condition against code trying to wait for one MultiXactId to finish;
477 * see notes in heapam.c.
478 *
479 * NB - we don't worry about our local MultiXactId cache here, because that
480 * is handled by the lower-level routines.
481 *
482 * Note: It is critical that MultiXactIds that come from an old cluster (i.e.
483 * one upgraded by pg_upgrade from a cluster older than this feature) are not
484 * passed in.
485 */
486 MultiXactId
488 {
489 MultiXactId newMulti;
499 /* MultiXactIdSetOldestMember() must have been called already. */
505 /*
506 * Note: we don't allow for old multis here. The reason is that the only
507 * caller of this function does a check that the multixact is no longer
508 * running.
509 */
513 {
514 MultiXactMember member;
516 /*
517 * The MultiXactId is obsolete. This can only happen if all the
518 * MultiXactId members stop running between the caller checking and
519 * passing it to us. It would be better to return that fact to the
520 * caller, but it would complicate the API and it's unlikely to happen
521 * too often, so just deal with it by creating a singleton MultiXact.
522 */
530 }
532 /*
533 * If the TransactionId is already a member of the MultiXactId with the
534 * same status, just return the existing MultiXactId.
535 */
537 {
540 {
545 }
546 }
548 /*
549 * Determine which of the members of the MultiXactId are still of
550 * interest. This is any running transaction, and also any transaction
551 * that grabbed something stronger than just a lock and was committed. (An
552 * update that aborted is of no interest here; and having more than one
553 * update Xid in a multixact would cause errors elsewhere.)
554 *
555 * Removing dead members is not just an optimization: freezing of tuples
556 * whose Xmax are multis depends on this behavior.
557 *
558 * Note we have the same race condition here as above: j could be 0 at the
559 * end of the loop.
560 */
565 {
569 {
572 }
573 }
585 }
587 /*
588 * MultiXactIdIsRunning
589 * Returns whether a MultiXactId is "running".
590 *
591 * We return true if at least one member of the given MultiXactId is still
592 * running. Note that a "false" result is certain not to change,
593 * because it is not legal to add members to an existing MultiXactId.
594 *
595 * Caller is expected to have verified that the multixact does not come from
596 * a pg_upgraded share-locked tuple.
597 */
598 bool
600 {
607 /*
608 * "false" here means we assume our callers have checked that the given
609 * multi cannot possibly come from a pg_upgraded database.
610 */
614 {
617 }
619 /*
620 * Checking for myself is cheap compared to looking in shared memory;
621 * return true if any live subtransaction of the current top-level
622 * transaction is a member.
623 *
624 * This is not needed for correctness, it's just a fast path.
625 */
627 {
629 {
633 }
634 }
636 /*
637 * This could be made faster by having another entry point in procarray.c,
638 * walking the PGPROC array only once for all the members. But in most
639 * cases nmembers should be small enough that it doesn't much matter.
640 */
642 {
644 {
649 }
650 }
657 }
659 /*
660 * MultiXactIdSetOldestMember
661 * Save the oldest MultiXactId this transaction could be a member of.
662 *
663 * We set the OldestMemberMXactId for a given transaction the first time it's
664 * going to do some operation that might require a MultiXactId (tuple lock,
665 * update or delete). We need to do this even if we end up using a
666 * TransactionId instead of a MultiXactId, because there is a chance that
667 * another transaction would add our XID to a MultiXactId.
668 *
669 * The value to set is the next-to-be-assigned MultiXactId, so this is meant to
670 * be called just before doing any such possibly-MultiXactId-able operation.
671 */
672 void
674 {
676 {
677 MultiXactId nextMXact;
679 /*
680 * You might think we don't need to acquire a lock here, since
681 * fetching and storing of TransactionIds is probably atomic, but in
682 * fact we do: suppose we pick up nextMXact and then lose the CPU for
683 * a long time. Someone else could advance nextMXact, and then
684 * another someone else could compute an OldestVisibleMXactId that
685 * would be after the value we are going to store when we get control
686 * back. Which would be wrong.
687 *
688 * Note that a shared lock is sufficient, because it's enough to stop
689 * someone from advancing nextMXact; and nobody else could be trying
690 * to write to our OldestMember entry, only reading (and we assume
691 * storing it is atomic.)
692 */
695 /*
696 * We have to beware of the possibility that nextMXact is in the
697 * wrapped-around state. We don't fix the counter itself here, but we
698 * must be sure to store a valid value in our array entry.
699 */
710 }
711 }
713 /*
714 * MultiXactIdSetOldestVisible
715 * Save the oldest MultiXactId this transaction considers possibly live.
716 *
717 * We set the OldestVisibleMXactId for a given transaction the first time
718 * it's going to inspect any MultiXactId. Once we have set this, we are
719 * guaranteed that SLRU data for MultiXactIds >= our own OldestVisibleMXactId
720 * won't be truncated away.
721 *
722 * The value to set is the oldest of nextMXact and all the valid per-backend
723 * OldestMemberMXactId[] entries. Because of the locking we do, we can be
724 * certain that no subsequent call to MultiXactIdSetOldestMember can set
725 * an OldestMemberMXactId[] entry older than what we compute here. Therefore
726 * there is no live transaction, now or later, that can be a member of any
727 * MultiXactId older than the OldestVisibleMXactId we compute here.
728 */
729 static void
731 {
733 {
734 MultiXactId oldestMXact;
739 /*
740 * We have to beware of the possibility that nextMXact is in the
741 * wrapped-around state. We don't fix the counter itself here, but we
742 * must be sure to store a valid value in our array entry.
743 */
749 {
755 }
763 }
764 }
766 /*
767 * ReadNextMultiXactId
768 * Return the next MultiXactId to be assigned, but don't allocate it
769 */
770 MultiXactId
772 {
773 MultiXactId mxid;
775 /* XXX we could presumably do this without a lock. */
784 }
786 /*
787 * ReadMultiXactIdRange
788 * Get the range of IDs that may still be referenced by a relation.
789 */
790 void
792 {
802 }
805 /*
806 * MultiXactIdCreateFromMembers
807 * Make a new MultiXactId from the specified set of members
808 *
809 * Make XLOG, SLRU and cache entries for a new MultiXactId, recording the
810 * given TransactionIds as members. Returns the newly created MultiXactId.
811 *
812 * NB: the passed members[] array will be sorted in-place.
813 */
814 MultiXactId
816 {
817 MultiXactId multi;
818 MultiXactOffset offset;
819 xl_multixact_create xlrec;
824 /*
825 * See if the same set of members already exists in our cache; if so, just
826 * re-use that MultiXactId. (Note: it might seem that looking in our
827 * cache is insufficient, and we ought to search disk to see if a
828 * duplicate definition already exists. But since we only ever create
829 * MultiXacts containing our own XID, in most cases any such MultiXacts
830 * were in fact created by us, and so will be in our cache. There are
831 * corner cases where someone else added us to a MultiXact without our
832 * knowledge, but it's not worth checking for.)
833 */
836 {
839 }
841 /* Verify that there is a single update Xid among the given members. */
842 {
847 {
849 {
854 }
855 }
856 }
858 /* Load the injection point before entering the critical section */
861 /*
862 * Assign the MXID and offsets range to use, and make sure there is space
863 * in the OFFSETs and MEMBERs files. NB: this routine does
864 * START_CRIT_SECTION().
865 *
866 * Note: unlike MultiXactIdCreate and MultiXactIdExpand, we do not check
867 * that we've called MultiXactIdSetOldestMember here. This is because
868 * this routine is used in some places to create new MultiXactIds of which
869 * the current backend is not a member, notably during freezing of multis
870 * in vacuum. During vacuum, in particular, it would be unacceptable to
871 * keep OldestMulti set, in case it runs for long.
872 */
877 /* Make an XLOG entry describing the new MXID. */
882 /*
883 * XXX Note: there's a lot of padding space in MultiXactMember. We could
884 * find a more compact representation of this Xlog record -- perhaps all
885 * the status flags in one XLogRecData, then all the xids in another one?
886 * Not clear that it's worth the trouble though.
887 */
894 /* Now enter the information into the OFFSETs and MEMBERs logs */
897 /* Done with critical section */
900 /* Store the new MultiXactId in the local cache, too */
906 }
908 /*
909 * RecordNewMultiXact
910 * Write info about a new multixact into the offsets and members files
911 *
912 * This is broken out of MultiXactIdCreateFromMembers so that xlog replay can
913 * use it.
914 */
915 static void
918 {
919 int64 pageno;
920 int64 prev_pageno;
934 /*
935 * Note: we pass the MultiXactId to SimpleLruReadPage as the "transaction"
936 * to complain about if there's any I/O error. This is kinda bogus, but
937 * since the errors will always give the full pathname, it should be clear
938 * enough that a MultiXactId is really involved. Perhaps someday we'll
939 * take the trouble to generalize the slru.c error reporting code.
940 */
949 /* Release MultiXactOffset SLRU lock. */
952 /*
953 * If anybody was waiting to know the offset of this multixact ID we just
954 * wrote, they can read it now, so wake them up.
955 */
961 {
964 uint32 flagsval;
977 {
978 /*
979 * MultiXactMember SLRU page is changed so check if this new page
980 * fall into the different SLRU bank then release the old bank's
981 * lock and acquire lock on the new bank.
982 */
985 {
991 }
994 }
1010 }
1014 }
1016 /*
1017 * GetNewMultiXactId
1018 * Get the next MultiXactId.
1019 *
1020 * Also, reserve the needed amount of space in the "members" area. The
1021 * starting offset of the reserved space is returned in *offset.
1022 *
1023 * This may generate XLOG records for expansion of the offsets and/or members
1024 * files. Unfortunately, we have to do that while holding MultiXactGenLock
1025 * to avoid race conditions --- the XLOG record for zeroing a page must appear
1026 * before any backend can possibly try to store data in that page!
1027 *
1028 * We start a critical section before advancing the shared counters. The
1029 * caller must end the critical section after writing SLRU data.
1030 */
1031 static MultiXactId
1033 {
1034 MultiXactId result;
1035 MultiXactOffset nextOffset;
1039 /* safety check, we should never get this far in a HS standby */
1045 /* Handle wraparound of the nextMXact counter */
1049 /* Assign the MXID */
1052 /*----------
1053 * Check to see if it's safe to assign another MultiXactId. This protects
1054 * against catastrophic data loss due to multixact wraparound. The basic
1055 * rules are:
1056 *
1057 * If we're past multiVacLimit or the safe threshold for member storage
1058 * space, or we don't know what the safe threshold for member storage is,
1059 * start trying to force autovacuum cycles.
1060 * If we're past multiWarnLimit, start issuing warnings.
1061 * If we're past multiStopLimit, refuse to create new MultiXactIds.
1062 *
1063 * Note these are pretty much the same protections in GetNewTransactionId.
1064 *----------
1065 */
1067 {
1068 /*
1069 * For safety's sake, we release MultiXactGenLock while sending
1070 * signals, warnings, etc. This is not so much because we care about
1071 * preserving concurrency in this situation, as to avoid any
1072 * possibility of deadlock while doing get_database_name(). First,
1073 * copy all the shared values we'll need in this path.
1074 */
1084 {
1087 /*
1088 * Immediately kick autovacuum into action as we're already in
1089 * ERROR territory.
1090 */
1093 /* complain even if that DB has disappeared */
1097 errmsg("database is not accepting commands that assign new MultiXactIds to avoid wraparound data loss in database \"%s\"",
1098 oldest_datname),
1100 "You might also need to commit or roll back old prepared transactions, or drop stale replication slots.")));
1101 else
1104 errmsg("database is not accepting commands that assign new MultiXactIds to avoid wraparound data loss in database with OID %u",
1105 oldest_datoid),
1107 "You might also need to commit or roll back old prepared transactions, or drop stale replication slots.")));
1108 }
1110 /*
1111 * To avoid swamping the postmaster with signals, we issue the autovac
1112 * request only once per 64K multis generated. This still gives
1113 * plenty of chances before we get into real trouble.
1114 */
1119 {
1122 /* complain even if that DB has disappeared */
1128 oldest_datname,
1131 "You might also need to commit or roll back old prepared transactions, or drop stale replication slots.")));
1132 else
1137 oldest_datoid,
1140 "You might also need to commit or roll back old prepared transactions, or drop stale replication slots.")));
1141 }
1143 /* Re-acquire lock and start over */
1148 }
1150 /* Make sure there is room for the MXID in the file. */
1153 /*
1154 * Reserve the members space, similarly to above. Also, be careful not to
1155 * return zero as the starting offset for any multixact. See
1156 * GetMultiXactIdMembers() for motivation.
1157 */
1160 {
1163 }
1164 else
1167 /*----------
1168 * Protect against overrun of the members space as well, with the
1169 * following rules:
1170 *
1171 * If we're past offsetStopLimit, refuse to generate more multis.
1172 * If we're close to offsetStopLimit, emit a warning.
1173 *
1174 * Arbitrarily, we start emitting warnings when we're 20 segments or less
1175 * from offsetStopLimit.
1176 *
1177 * Note we haven't updated the shared state yet, so if we fail at this
1178 * point, the multixact ID we grabbed can still be used by the next guy.
1179 *
1180 * Note that there is no point in forcing autovacuum runs here: the
1181 * multixact freeze settings would have to be reduced for that to have any
1182 * effect.
1183 *----------
1184 */
1185 #define OFFSET_WARN_SEGMENTS 20
1188 nmembers))
1189 {
1190 /* see comment in the corresponding offsets wraparound case */
1196 errdetail_plural("This command would create a multixact with %u members, but the remaining space is only enough for %u member.",
1197 "This command would create a multixact with %u members, but the remaining space is only enough for %u members.",
1199 nmembers,
1201 errhint("Execute a database-wide VACUUM in database with OID %u with reduced \"vacuum_multixact_freeze_min_age\" and \"vacuum_multixact_freeze_table_age\" settings.",
1203 }
1205 /*
1206 * Check whether we should kick autovacuum into action, to prevent members
1207 * wraparound. NB we use a much larger window to trigger autovacuum than
1208 * just the warning limit. The warning is just a measure of last resort -
1209 * this is in line with GetNewTransactionId's behaviour.
1210 */
1214 {
1215 /*
1216 * To avoid swamping the postmaster with signals, we issue the autovac
1217 * request only when crossing a segment boundary. With default
1218 * compilation settings that's roughly after 50k members. This still
1219 * gives plenty of chances before we get into real trouble.
1220 */
1224 }
1228 nextOffset,
1237 errhint("Execute a database-wide VACUUM in that database with reduced \"vacuum_multixact_freeze_min_age\" and \"vacuum_multixact_freeze_table_age\" settings.")));
1241 /*
1242 * Critical section from here until caller has written the data into the
1243 * just-reserved SLRU space; we don't want to error out with a partly
1244 * written MultiXact structure. (In particular, failing to write our
1245 * start offset after advancing nextMXact would effectively corrupt the
1246 * previous MultiXact.)
1247 */
1250 /*
1251 * Advance counters. As in GetNewTransactionId(), this must not happen
1252 * until after file extension has succeeded!
1253 *
1254 * We don't care about MultiXactId wraparound here; it will be handled by
1255 * the next iteration. But note that nextMXact may be InvalidMultiXactId
1256 * or the first value on a segment-beginning page after this routine
1257 * exits, so anyone else looking at the variable must be prepared to deal
1258 * with either case. Similarly, nextOffset may be zero, but we won't use
1259 * that as the actual start offset of the next multixact.
1260 */
1269 }
1271 /*
1272 * GetMultiXactIdMembers
1273 * Return the set of MultiXactMembers that make up a MultiXactId
1274 *
1275 * Return value is the number of members found, or -1 if there are none,
1276 * and *members is set to a newly palloc'ed array of members. It's the
1277 * caller's responsibility to free it when done with it.
1278 *
1279 * from_pgupgrade must be passed as true if and only if only the multixact
1280 * corresponds to a value from a tuple that was locked in a 9.2-or-older
1281 * installation and later pg_upgrade'd (that is, the infomask is
1282 * HEAP_LOCKED_UPGRADED). In this case, we know for certain that no members
1283 * can still be running, so we return -1 just like for an empty multixact
1284 * without any further checking. It would be wrong to try to resolve such a
1285 * multixact: either the multixact is within the current valid multixact
1286 * range, in which case the returned result would be bogus, or outside that
1287 * range, in which case an error would be raised.
1288 *
1289 * In all other cases, the passed multixact must be within the known valid
1290 * range, that is, greater to or equal than oldestMultiXactId, and less than
1291 * nextMXact. Otherwise, an error is raised.
1292 *
1293 * isLockOnly must be set to true if caller is certain that the given multi
1294 * is used only to lock tuples; can be false without loss of correctness,
1295 * but passing a true means we can return quickly without checking for
1296 * old updates.
1297 */
1298 int
1301 {
1302 int64 pageno;
1303 int64 prev_pageno;
1307 MultiXactOffset offset;
1310 MultiXactId oldestMXact;
1311 MultiXactId nextMXact;
1312 MultiXactId tmpMXact;
1313 MultiXactOffset nextOffset;
1321 {
1324 }
1326 /* See if the MultiXactId is in the local cache */
1329 {
1333 }
1335 /* Set our OldestVisibleMXactId[] entry if we didn't already */
1338 /*
1339 * If we know the multi is used only for locking and not for updates, then
1340 * we can skip checking if the value is older than our oldest visible
1341 * multi. It cannot possibly still be running.
1342 */
1345 {
1349 }
1351 /*
1352 * We check known limits on MultiXact before resorting to the SLRU area.
1353 *
1354 * An ID older than MultiXactState->oldestMultiXactId cannot possibly be
1355 * useful; it has already been removed, or will be removed shortly, by
1356 * truncation. If one is passed, an error is raised.
1357 *
1358 * Also, an ID >= nextMXact shouldn't ever be seen here; if it is seen, it
1359 * implies undetected ID wraparound has occurred. This raises a hard
1360 * error.
1361 *
1362 * Shared lock is enough here since we aren't modifying any global state.
1363 * Acquire it just long enough to grab the current counter values. We may
1364 * need both nextMXact and nextOffset; see below.
1365 */
1378 multi)));
1384 multi)));
1386 /*
1387 * Find out the offset at which we need to start reading MultiXactMembers
1388 * and the number of members in the multixact. We determine the latter as
1389 * the difference between this multixact's starting offset and the next
1390 * one's. However, there are some corner cases to worry about:
1391 *
1392 * 1. This multixact may be the latest one created, in which case there is
1393 * no next one to look at. In this case the nextOffset value we just
1394 * saved is the correct endpoint.
1395 *
1396 * 2. The next multixact may still be in process of being filled in: that
1397 * is, another process may have done GetNewMultiXactId but not yet written
1398 * the offset entry for that ID. In that scenario, it is guaranteed that
1399 * the offset entry for that multixact exists (because GetNewMultiXactId
1400 * won't release MultiXactGenLock until it does) but contains zero
1401 * (because we are careful to pre-zero offset pages). Because
1402 * GetNewMultiXactId will never return zero as the starting offset for a
1403 * multixact, when we read zero as the next multixact's offset, we know we
1404 * have this case. We handle this by sleeping on the condition variable
1405 * we have just for this; the process in charge will signal the CV as soon
1406 * as it has finished writing the multixact offset.
1407 *
1408 * 3. Because GetNewMultiXactId increments offset zero to offset one to
1409 * handle case #2, there is an ambiguity near the point of offset
1410 * wraparound. If we see next multixact's offset is one, is that our
1411 * multixact's actual endpoint, or did it end at zero with a subsequent
1412 * increment? We handle this using the knowledge that if the zero'th
1413 * member slot wasn't filled, it'll contain zero, and zero isn't a valid
1414 * transaction ID so it can't be a multixact member. Therefore, if we
1415 * read a zero from the members array, just ignore it.
1416 *
1417 * This is all pretty messy, but the mess occurs only in infrequent corner
1418 * cases, so it seems better than holding the MultiXactGenLock for a long
1419 * time on every multixact creation.
1420 */
1421 retry:
1425 /* Acquire the bank lock for the page we need. */
1436 /*
1437 * Use the same increment rule as GetNewMultiXactId(), that is, don't
1438 * handle wraparound explicitly until needed.
1439 */
1443 {
1444 /* Corner case 1: there is no next multixact */
1446 }
1447 else
1448 {
1449 MultiXactOffset nextMXOffset;
1451 /* handle wraparound if needed */
1461 {
1464 /*
1465 * Since we're going to access a different SLRU page, if this page
1466 * falls under a different bank, release the old bank's lock and
1467 * acquire the lock of the new bank.
1468 */
1471 {
1475 }
1477 }
1484 {
1485 /* Corner case 2: next multixact is still being filled in */
1492 WAIT_EVENT_MULTIXACT_CREATION);
1495 }
1498 }
1503 /*
1504 * If we slept above, clean up state; it's no longer needed.
1505 */
1514 {
1525 {
1528 /*
1529 * Since we're going to access a different SLRU page, if this page
1530 * falls under a different bank, release the old bank's lock and
1531 * acquire the lock of the new bank.
1532 */
1535 {
1540 }
1544 }
1550 {
1551 /* Corner case 3: we must be looking at unused slot zero */
1554 }
1562 truelength++;
1563 }
1567 /* A multixid with zero members should not happen */
1570 /*
1571 * Copy the result into the local cache.
1572 */
1579 }
1581 /*
1582 * mxactMemberComparator
1583 * qsort comparison function for MultiXactMember
1584 *
1585 * We can't use wraparound comparison for XIDs because that does not respect
1586 * the triangle inequality! Any old sort order will do.
1587 */
1588 static int
1590 {
1603 }
1605 /*
1606 * mXactCacheGetBySet
1607 * returns a MultiXactId from the cache based on the set of
1608 * TransactionIds that compose it, or InvalidMultiXactId if
1609 * none matches.
1610 *
1611 * This is helpful, for example, if two transactions want to lock a huge
1612 * table. By using the cache, the second will use the same MultiXactId
1613 * for the majority of tuples, thus keeping MultiXactId usage low (saving
1614 * both I/O and wraparound issues).
1615 *
1616 * NB: the passed members array will be sorted in-place.
1617 */
1618 static MultiXactId
1620 {
1621 dlist_iter iter;
1626 /* sort the array so comparison is easy */
1630 {
1637 /*
1638 * We assume the cache entries are sorted, and that the unused bits in
1639 * "status" are zeroed.
1640 */
1642 {
1646 }
1647 }
1651 }
1653 /*
1654 * mXactCacheGetById
1655 * returns the composing MultiXactMember set from the cache for a
1656 * given MultiXactId, if present.
1657 *
1658 * If successful, *xids is set to the address of a palloc'd copy of the
1659 * MultiXactMember set. Return value is number of members, or -1 on failure.
1660 */
1661 static int
1663 {
1664 dlist_iter iter;
1669 {
1674 {
1676 Size size;
1688 /*
1689 * Note we modify the list while not using a modifiable iterator.
1690 * This is acceptable only because we exit the iteration
1691 * immediately afterwards.
1692 */
1697 }
1698 }
1702 }
1704 /*
1705 * mXactCachePut
1706 * Add a new MultiXactId and its composing set into the local cache.
1707 */
1708 static void
1710 {
1717 {
1718 /* The cache only lives as long as the current transaction */
1722 ALLOCSET_SMALL_SIZES);
1723 }
1734 /* mXactCacheGetBySet assumes the entries are sorted, so sort them */
1739 {
1750 }
1751 }
1755 {
1757 {
1773 }
1774 }
1778 {
1780 StringInfoData buf;
1799 }
1801 /*
1802 * AtEOXact_MultiXact
1803 * Handle transaction end for MultiXact
1804 *
1805 * This is called at top transaction commit or abort (we don't care which).
1806 */
1807 void
1809 {
1810 /*
1811 * Reset our OldestMemberMXactId and OldestVisibleMXactId values, both of
1812 * which should only be valid while within a transaction.
1813 *
1814 * We assume that storing a MultiXactId is atomic and so we need not take
1815 * MultiXactGenLock to do this.
1816 */
1820 /*
1821 * Discard the local MultiXactId cache. Since MXactContext was created as
1822 * a child of TopTransactionContext, we needn't delete it explicitly.
1823 */
1826 }
1828 /*
1829 * AtPrepare_MultiXact
1830 * Save multixact state at 2PC transaction prepare
1831 *
1832 * In this phase, we only store our OldestMemberMXactId value in the two-phase
1833 * state file.
1834 */
1835 void
1837 {
1843 }
1845 /*
1846 * PostPrepare_MultiXact
1847 * Clean up after successful PREPARE TRANSACTION
1848 */
1849 void
1851 {
1852 MultiXactId myOldestMember;
1854 /*
1855 * Transfer our OldestMemberMXactId value to the slot reserved for the
1856 * prepared transaction.
1857 */
1860 {
1863 /*
1864 * Even though storing MultiXactId is atomic, acquire lock to make
1865 * sure others see both changes, not just the reset of the slot of the
1866 * current backend. Using a volatile pointer might suffice, but this
1867 * isn't a hot spot.
1868 */
1875 }
1877 /*
1878 * We don't need to transfer OldestVisibleMXactId value, because the
1879 * transaction is not going to be looking at any more multixacts once it's
1880 * prepared.
1881 *
1882 * We assume that storing a MultiXactId is atomic and so we need not take
1883 * MultiXactGenLock to do this.
1884 */
1887 /*
1888 * Discard the local MultiXactId cache like in AtEOXact_MultiXact.
1889 */
1892 }
1894 /*
1895 * multixact_twophase_recover
1896 * Recover the state of a prepared transaction at startup
1897 */
1898 void
1901 {
1903 MultiXactId oldestMember;
1905 /*
1906 * Get the oldest member XID from the state file record, and set it in the
1907 * OldestMemberMXactId slot reserved for this prepared transaction.
1908 */
1913 }
1915 /*
1916 * multixact_twophase_postcommit
1917 * Similar to AtEOXact_MultiXact but for COMMIT PREPARED
1918 */
1919 void
1922 {
1928 }
1930 /*
1931 * multixact_twophase_postabort
1932 * This is actually just the same as the COMMIT case.
1933 */
1934 void
1937 {
1939 }
1941 /*
1942 * Initialization of shared memory for MultiXact. We use two SLRU areas,
1943 * thus double memory. Also, reserve space for the shared MultiXactState
1944 * struct and the per-backend MultiXactId arrays (two of those, too).
1945 */
1946 Size
1948 {
1949 Size size;
1951 /* We need 2*MaxOldestSlot perBackendXactIds[] entries */
1952 #define SHARED_MULTIXACT_STATE_SIZE \
1953 add_size(offsetof(MultiXactStateData, perBackendXactIds), \
1954 mul_size(sizeof(MultiXactId) * 2, MaxOldestSlot))
1961 }
1963 void
1965 {
1976 LWTRANCHE_MULTIXACTOFFSET_SLRU,
1977 SYNC_HANDLER_MULTIXACT_OFFSET,
1983 LWTRANCHE_MULTIXACTMEMBER_SLRU,
1984 SYNC_HANDLER_MULTIXACT_MEMBER,
1986 /* doesn't call SimpleLruTruncate() or meet criteria for unit tests */
1988 /* Initialize our shared state struct */
1990 SHARED_MULTIXACT_STATE_SIZE,
1993 {
1996 /* Make sure we zero out the per-backend state */
1999 }
2000 else
2003 /*
2004 * Set up array pointers.
2005 */
2008 }
2010 /*
2011 * GUC check_hook for multixact_offset_buffers
2012 */
2013 bool
2015 {
2017 }
2019 /*
2020 * GUC check_hook for multixact_member_buffers
2021 */
2022 bool
2024 {
2026 }
2028 /*
2029 * This func must be called ONCE on system install. It creates the initial
2030 * MultiXact segments. (The MultiXacts directories are assumed to have been
2031 * created by initdb, and MultiXactShmemInit must have been called already.)
2032 */
2033 void
2035 {
2042 /* Create and zero the first page of the offsets log */
2045 /* Make sure it's written out */
2054 /* Create and zero the first page of the members log */
2057 /* Make sure it's written out */
2062 }
2064 /*
2065 * Initialize (or reinitialize) a page of MultiXactOffset to zeroes.
2066 * If writeXlog is true, also emit an XLOG record saying we did this.
2067 *
2068 * The page is not actually written, just set up in shared memory.
2069 * The slot number of the new page is returned.
2070 *
2071 * Control lock must be held at entry, and will be held at exit.
2072 */
2073 static int
2075 {
2084 }
2086 /*
2087 * Ditto, for MultiXactMember
2088 */
2089 static int
2091 {
2100 }
2102 /*
2103 * MaybeExtendOffsetSlru
2104 * Extend the offsets SLRU area, if necessary
2105 *
2106 * After a binary upgrade from <= 9.2, the pg_multixact/offsets SLRU area might
2107 * contain files that are shorter than necessary; this would occur if the old
2108 * installation had used multixacts beyond the first page (files cannot be
2109 * copied, because the on-disk representation is different). pg_upgrade would
2110 * update pg_control to set the next offset value to be at that position, so
2111 * that tuples marked as locked by such MultiXacts would be seen as visible
2112 * without having to consult multixact. However, trying to create and use a
2113 * new MultiXactId would result in an error because the page on which the new
2114 * value would reside does not exist. This routine is in charge of creating
2115 * such pages.
2116 */
2117 static void
2119 {
2120 int64 pageno;
2129 {
2132 /*
2133 * Fortunately for us, SimpleLruWritePage is already prepared to deal
2134 * with creating a new segment file even if the page we're writing is
2135 * not the first in it, so this is enough.
2136 */
2139 }
2142 }
2144 /*
2145 * This must be called ONCE during postmaster or standalone-backend startup.
2146 *
2147 * StartupXLOG has already established nextMXact/nextOffset by calling
2148 * MultiXactSetNextMXact and/or MultiXactAdvanceNextMXact, and the oldestMulti
2149 * info from pg_control and/or MultiXactAdvanceOldest, but we haven't yet
2150 * replayed WAL.
2151 */
2152 void
2154 {
2157 int64 pageno;
2159 /*
2160 * Initialize offset's idea of the latest page number.
2161 */
2164 pageno);
2166 /*
2167 * Initialize member's idea of the latest page number.
2168 */
2171 pageno);
2172 }
2174 /*
2175 * This must be called ONCE at the end of startup/recovery.
2176 */
2177 void
2179 {
2180 MultiXactId nextMXact;
2181 MultiXactOffset offset;
2182 MultiXactId oldestMXact;
2183 Oid oldestMXactDB;
2184 int64 pageno;
2195 /* Clean up offsets state */
2197 /*
2198 * (Re-)Initialize our idea of the latest page number for offsets.
2199 */
2202 pageno);
2204 /*
2205 * Zero out the remainder of the current offsets page. See notes in
2206 * TrimCLOG() for background. Unlike CLOG, some WAL record covers every
2207 * pg_multixact SLRU mutation. Since, also unlike CLOG, we ignore the WAL
2208 * rule "write xlog before data," nextMXact successors may carry obsolete,
2209 * nonzero offset values. Zero those so case 2 of GetMultiXactIdMembers()
2210 * operates normally.
2211 */
2214 {
2228 }
2230 /*
2231 * And the same for members.
2232 *
2233 * (Re-)Initialize our idea of the latest page number for members.
2234 */
2237 pageno);
2239 /*
2240 * Zero out the remainder of the current members page. See notes in
2241 * TrimCLOG() for motivation.
2242 */
2245 {
2259 /*
2260 * Note: we don't need to zero out the flag bits in the remaining
2261 * members of the current group, because they are always reset before
2262 * writing.
2263 */
2267 }
2269 /* signal that we're officially up */
2274 /* Now compute how far away the next members wraparound is. */
2276 }
2278 /*
2279 * Get the MultiXact data to save in a checkpoint record
2280 */
2281 void
2287 {
2298 }
2300 /*
2301 * Perform a checkpoint --- either during shutdown, or on-the-fly
2302 */
2303 void
2305 {
2308 /*
2309 * Write dirty MultiXact pages to disk. This may result in sync requests
2310 * queued for later handling by ProcessSyncRequests(), as part of the
2311 * checkpoint.
2312 */
2317 }
2319 /*
2320 * Set the next-to-be-assigned MultiXactId and offset
2321 *
2322 * This is used when we can determine the correct next ID/offset exactly
2323 * from a checkpoint record. Although this is only called during bootstrap
2324 * and XLog replay, we take the lock in case any hot-standby backends are
2325 * examining the values.
2326 */
2327 void
2329 MultiXactOffset nextMultiOffset)
2330 {
2338 /*
2339 * During a binary upgrade, make sure that the offsets SLRU is large
2340 * enough to contain the next value that would be created.
2341 *
2342 * We need to do this pretty early during the first startup in binary
2343 * upgrade mode: before StartupMultiXact() in fact, because this routine
2344 * is called even before that by StartupXLOG(). And we can't do it
2345 * earlier than at this point, because during that first call of this
2346 * routine we determine the MultiXactState->nextMXact value that
2347 * MaybeExtendOffsetSlru needs.
2348 */
2351 }
2353 /*
2354 * Determine the last safe MultiXactId to allocate given the currently oldest
2355 * datminmxid (ie, the oldest MultiXactId that might exist in any database
2356 * of our cluster), and the OID of the (or a) database with that value.
2357 *
2358 * is_startup is true when we are just starting the cluster, false when we
2359 * are updating state in a running cluster. This only affects log messages.
2360 */
2361 void
2364 {
2365 MultiXactId multiVacLimit;
2366 MultiXactId multiWarnLimit;
2367 MultiXactId multiStopLimit;
2368 MultiXactId multiWrapLimit;
2369 MultiXactId curMulti;
2374 /*
2375 * We pretend that a wrap will happen halfway through the multixact ID
2376 * space, but that's not really true, because multixacts wrap differently
2377 * from transaction IDs. Note that, separately from any concern about
2378 * multixact IDs wrapping, we must ensure that multixact members do not
2379 * wrap. Limits for that are set in SetOffsetVacuumLimit, not here.
2380 */
2385 /*
2386 * We'll refuse to continue assigning MultiXactIds once we get within 3M
2387 * multi of data loss. See SetTransactionIdLimit.
2388 */
2393 /*
2394 * We'll start complaining loudly when we get within 40M multis of data
2395 * loss. This is kind of arbitrary, but if you let your gas gauge get
2396 * down to 2% of full, would you be looking for the next gas station? We
2397 * need to be fairly liberal about this number because there are lots of
2398 * scenarios where most transactions are done by automatic clients that
2399 * won't pay attention to warnings. (No, we're not gonna make this
2400 * configurable. If you know enough to configure it, you know enough to
2401 * not get in this kind of trouble in the first place.)
2402 */
2407 /*
2408 * We'll start trying to force autovacuums when oldest_datminmxid gets to
2409 * be more than autovacuum_multixact_freeze_max_age mxids old.
2410 *
2411 * Note: autovacuum_multixact_freeze_max_age is a PGC_POSTMASTER parameter
2412 * so that we don't have to worry about dealing with on-the-fly changes in
2413 * its value. See SetTransactionIdLimit.
2414 */
2419 /* Grab lock for just long enough to set the new limit values */
2430 /* Log the info */
2435 /*
2436 * Computing the actual limits is only possible once the data directory is
2437 * in a consistent state. There's no need to compute the limits while
2438 * still replaying WAL - no decisions about new multis are made even
2439 * though multixact creations might be replayed. So we'll only do further
2440 * checks after TrimMultiXact() has been called.
2441 */
2447 /* Set limits for offset vacuum. */
2450 /*
2451 * If past the autovacuum force point, immediately signal an autovac
2452 * request. The reason for this is that autovac only processes one
2453 * database per invocation. Once it's finished cleaning up the oldest
2454 * database, it'll call here, and we'll signal the postmaster to start
2455 * another iteration immediately if there are still any old databases.
2456 */
2461 /* Give an immediate warning if past the wrap warn point */
2463 {
2466 /*
2467 * We can be called when not inside a transaction, for example during
2468 * StartupXLOG(). In such a case we cannot do database access, so we
2469 * must just report the oldest DB's OID.
2470 *
2471 * Note: it's also possible that get_database_name fails and returns
2472 * NULL, for example because the database just got dropped. We'll
2473 * still warn, even though the warning might now be unnecessary.
2474 */
2477 else
2485 oldest_datname,
2487 errhint("To avoid MultiXactId assignment failures, execute a database-wide VACUUM in that database.\n"
2488 "You might also need to commit or roll back old prepared transactions, or drop stale replication slots.")));
2489 else
2494 oldest_datoid,
2496 errhint("To avoid MultiXactId assignment failures, execute a database-wide VACUUM in that database.\n"
2497 "You might also need to commit or roll back old prepared transactions, or drop stale replication slots.")));
2498 }
2499 }
2501 /*
2502 * Ensure the next-to-be-assigned MultiXactId is at least minMulti,
2503 * and similarly nextOffset is at least minMultiOffset.
2504 *
2505 * This is used when we can determine minimum safe values from an XLog
2506 * record (either an on-line checkpoint or an mxact creation log entry).
2507 * Although this is only called during XLog replay, we take the lock in case
2508 * any hot-standby backends are examining the values.
2509 */
2510 void
2512 MultiXactOffset minMultiOffset)
2513 {
2516 {
2519 }
2521 {
2523 minMultiOffset);
2525 }
2527 }
2529 /*
2530 * Update our oldestMultiXactId value, but only if it's more recent than what
2531 * we had.
2532 *
2533 * This may only be called during WAL replay.
2534 */
2535 void
2537 {
2542 }
2544 /*
2545 * Make sure that MultiXactOffset has room for a newly-allocated MultiXactId.
2546 *
2547 * NB: this is called while holding MultiXactGenLock. We want it to be very
2548 * fast most of the time; even when it's not so fast, no actual I/O need
2549 * happen unless we're forced to write out a dirty log or xlog page to make
2550 * room in shared memory.
2551 */
2552 static void
2554 {
2555 int64 pageno;
2558 /*
2559 * No work except at first MultiXactId of a page. But beware: just after
2560 * wraparound, the first MultiXactId of page zero is FirstMultiXactId.
2561 */
2571 /* Zero the page and make an XLOG entry about it */
2575 }
2577 /*
2578 * Make sure that MultiXactMember has room for the members of a newly-
2579 * allocated MultiXactId.
2580 *
2581 * Like the above routine, this is called while holding MultiXactGenLock;
2582 * same comments apply.
2583 */
2584 static void
2586 {
2587 /*
2588 * It's possible that the members span more than one page of the members
2589 * file, so we loop to ensure we consider each page. The coding is not
2590 * optimal if the members span several pages, but that seems unusual
2591 * enough to not worry much about.
2592 */
2594 {
2597 uint32 difference;
2599 /*
2600 * Only zero when at first entry of a page.
2601 */
2605 {
2606 int64 pageno;
2614 /* Zero the page and make an XLOG entry about it */
2618 }
2620 /*
2621 * Compute the number of items till end of current page. Careful: if
2622 * addition of unsigned ints wraps around, we're at the last page of
2623 * the last segment; since that page holds a different number of items
2624 * than other pages, we need to do it differently.
2625 */
2627 {
2628 /*
2629 * This is the last page of the last segment; we can compute the
2630 * number of items left to allocate in it without modulo
2631 * arithmetic.
2632 */
2634 }
2635 else
2638 /*
2639 * Advance to next page, taking care to properly handle the wraparound
2640 * case. OK if nmembers goes negative.
2641 */
2644 }
2645 }
2647 /*
2648 * GetOldestMultiXactId
2649 *
2650 * Return the oldest MultiXactId that's still possibly still seen as live by
2651 * any running transaction. Older ones might still exist on disk, but they no
2652 * longer have any running member transaction.
2653 *
2654 * It's not safe to truncate MultiXact SLRU segments on the value returned by
2655 * this function; however, it can be set as the new relminmxid for any table
2656 * that VACUUM knows has no remaining MXIDs < the same value. It is only safe
2657 * to truncate SLRUs when no table can possibly still have a referencing MXID.
2658 */
2659 MultiXactId
2661 {
2662 MultiXactId oldestMXact;
2663 MultiXactId nextMXact;
2666 /*
2667 * This is the oldest valid value among all the OldestMemberMXactId[] and
2668 * OldestVisibleMXactId[] entries, or nextMXact if none are valid.
2669 */
2672 /*
2673 * We have to beware of the possibility that nextMXact is in the
2674 * wrapped-around state. We don't fix the counter itself here, but we
2675 * must be sure to use a valid value in our calculation.
2676 */
2683 {
2684 MultiXactId thisoldest;
2694 }
2699 }
2701 /*
2702 * Determine how aggressively we need to vacuum in order to prevent member
2703 * wraparound.
2704 *
2705 * To do so determine what's the oldest member offset and install the limit
2706 * info in MultiXactState, where it can be used to prevent overrun of old data
2707 * in the members SLRU area.
2708 *
2709 * The return value is true if emergency autovacuum is required and false
2710 * otherwise.
2711 */
2712 static bool
2714 {
2715 MultiXactId oldestMultiXactId;
2716 MultiXactId nextMXact;
2718 MultiXactOffset prevOldestOffset;
2719 MultiXactOffset nextOffset;
2723 MultiXactOffset prevOffsetStopLimit;
2725 /*
2726 * NB: Have to prevent concurrent truncation, we might otherwise try to
2727 * lookup an oldestMulti that's concurrently getting truncated away.
2728 */
2731 /* Read relevant fields from shared memory. */
2742 /*
2743 * Determine the offset of the oldest multixact. Normally, we can read
2744 * the offset from the multixact itself, but there's an important special
2745 * case: if there are no multixacts in existence at all, oldestMXact
2746 * obviously can't point to one. It will instead point to the multixact
2747 * ID that will be assigned the next time one is needed.
2748 */
2750 {
2751 /*
2752 * When the next multixact gets created, it will be stored at the next
2753 * offset.
2754 */
2757 }
2758 else
2759 {
2760 /*
2761 * Figure out where the oldest existing multixact's offsets are
2762 * stored. Due to bugs in early release of PostgreSQL 9.3.X and 9.4.X,
2763 * the supposedly-earliest multixact might not really exist. We are
2764 * careful not to fail in that case.
2765 */
2766 oldestOffsetKnown =
2772 oldestOffset)));
2773 else
2775 (errmsg("MultiXact member wraparound protections are disabled because oldest checkpointed MultiXact %u does not exist on disk",
2776 oldestMultiXactId)));
2777 }
2781 /*
2782 * If we can, compute limits (and install them MultiXactState) to prevent
2783 * overrun of old data in the members SLRU area. We can only do so if the
2784 * oldest offset is known though.
2785 */
2787 {
2788 /* move back to start of the corresponding segment */
2792 /* always leave one segment before the wraparound point */
2802 }
2804 {
2805 /*
2806 * If we failed to get the oldest offset this time, but we have a
2807 * value from a previous pass through this function, use the old
2808 * values rather than automatically forcing an emergency autovacuum
2809 * cycle again.
2810 */
2814 }
2816 /* Install the computed values */
2823 /*
2824 * Do we need an emergency autovacuum? If we're not sure, assume yes.
2825 */
2828 }
2830 /*
2831 * Return whether adding "distance" to "start" would move past "boundary".
2832 *
2833 * We use this to determine whether the addition is "wrapping around" the
2834 * boundary point, hence the name. The reason we don't want to use the regular
2835 * 2^31-modulo arithmetic here is that we want to be able to use the whole of
2836 * the 2^32-1 space here, allowing for more multixacts than would fit
2837 * otherwise.
2838 */
2839 static bool
2841 uint32 distance)
2842 {
2843 MultiXactOffset finish;
2845 /*
2846 * Note that offset number 0 is not used (see GetMultiXactIdMembers), so
2847 * if the addition wraps around the UINT_MAX boundary, skip that value.
2848 */
2851 finish++;
2853 /*-----------------------------------------------------------------------
2854 * When the boundary is numerically greater than the starting point, any
2855 * value numerically between the two is not wrapped:
2856 *
2857 * <----S----B---->
2858 * [---) = F wrapped past B (and UINT_MAX)
2859 * [---) = F not wrapped
2860 * [----] = F wrapped past B
2861 *
2862 * When the boundary is numerically less than the starting point (i.e. the
2863 * UINT_MAX wraparound occurs somewhere in between) then all values in
2864 * between are wrapped:
2865 *
2866 * <----B----S---->
2867 * [---) = F not wrapped past B (but wrapped past UINT_MAX)
2868 * [---) = F wrapped past B (and UINT_MAX)
2869 * [----] = F not wrapped
2870 *-----------------------------------------------------------------------
2871 */
2874 else
2876 }
2878 /*
2879 * Find the starting offset of the given MultiXactId.
2880 *
2881 * Returns false if the file containing the multi does not exist on disk.
2882 * Otherwise, returns true and sets *result to the starting member offset.
2883 *
2884 * This function does not prevent concurrent truncation, so if that's
2885 * required, the caller has to protect against that.
2886 */
2887 static bool
2889 {
2890 MultiXactOffset offset;
2891 int64 pageno;
2901 /*
2902 * Write out dirty data, so PhysicalPageExists can work correctly.
2903 */
2910 /* lock is acquired by SimpleLruReadPage_ReadOnly */
2919 }
2921 /*
2922 * Determine how many multixacts, and how many multixact members, currently
2923 * exist. Return false if unable to determine.
2924 */
2925 static bool
2927 {
2928 MultiXactOffset nextOffset;
2929 MultiXactOffset oldestOffset;
2930 MultiXactId oldestMultiXactId;
2931 MultiXactId nextMultiXactId;
2948 }
2950 /*
2951 * Multixact members can be removed once the multixacts that refer to them
2952 * are older than every datminmxid. autovacuum_multixact_freeze_max_age and
2953 * vacuum_multixact_freeze_table_age work together to make sure we never have
2954 * too many multixacts; we hope that, at least under normal circumstances,
2955 * this will also be sufficient to keep us from using too many offsets.
2956 * However, if the average multixact has many members, we might exhaust the
2957 * members space while still using few enough members that these limits fail
2958 * to trigger relminmxid advancement by VACUUM. At that point, we'd have no
2959 * choice but to start failing multixact-creating operations with an error.
2960 *
2961 * To prevent that, if more than a threshold portion of the members space is
2962 * used, we effectively reduce autovacuum_multixact_freeze_max_age and
2963 * to a value just less than the number of multixacts in use. We hope that
2964 * this will quickly trigger autovacuuming on the table or tables with the
2965 * oldest relminmxid, thus allowing datminmxid values to advance and removing
2966 * some members.
2967 *
2968 * As the fraction of the member space currently in use grows, we become
2969 * more aggressive in clamping this value. That not only causes autovacuum
2970 * to ramp up, but also makes any manual vacuums the user issues more
2971 * aggressive. This happens because vacuum_get_cutoffs() will clamp the
2972 * freeze table and the minimum freeze age cutoffs based on the effective
2973 * autovacuum_multixact_freeze_max_age this function returns. In the worst
2974 * case, we'll claim the freeze_max_age to zero, and every vacuum of any
2975 * table will freeze every multixact.
2976 */
2977 int
2979 {
2980 MultiXactOffset members;
2981 uint32 multixacts;
2982 uint32 victim_multixacts;
2986 /* If we can't determine member space utilization, assume the worst. */
2990 /* If member space utilization is low, no special action is required. */
2994 /*
2995 * Compute a target for relminmxid advancement. The number of multixacts
2996 * we try to eliminate from the system is based on how far we are past
2997 * MULTIXACT_MEMBER_SAFE_THRESHOLD.
2998 */
3003 /* fraction could be > 1.0, but lowest possible freeze age is zero */
3008 /*
3009 * Clamp to autovacuum_multixact_freeze_max_age, so that we never make
3010 * autovacuum less aggressive than it would otherwise be.
3011 */
3013 }
3016 {
3017 int64 earliestExistingPage;
3020 /*
3021 * SlruScanDirectory callback
3022 * This callback determines the earliest existing page number.
3023 */
3024 static bool
3026 {
3031 {
3033 }
3036 }
3039 /*
3040 * Delete members segments [oldest, newOldest)
3041 *
3042 * The members SLRU can, in contrast to the offsets one, be filled to almost
3043 * the full range at once. This means SimpleLruTruncate() can't trivially be
3044 * used - instead the to-be-deleted range is computed using the offsets
3045 * SLRU. C.f. TruncateMultiXact().
3046 */
3047 static void
3049 {
3055 /*
3056 * Delete all the segments but the last one. The last segment can still
3057 * contain, possibly partially, valid data.
3058 */
3060 {
3065 /* move to next segment, handling wraparound correctly */
3068 else
3070 }
3071 }
3073 /*
3074 * Delete offsets segments [oldest, newOldest)
3075 */
3076 static void
3078 {
3079 /*
3080 * We step back one multixact to avoid passing a cutoff page that hasn't
3081 * been created yet in the rare case that oldestMulti would be the first
3082 * item on a page and oldestMulti == nextMulti. In that case, if we
3083 * didn't subtract one, we'd trigger SimpleLruTruncate's wraparound
3084 * detection.
3085 */
3088 }
3090 /*
3091 * Remove all MultiXactOffset and MultiXactMember segments before the oldest
3092 * ones still of interest.
3093 *
3094 * This is only called on a primary as part of vacuum (via
3095 * vac_truncate_clog()). During recovery truncation is done by replaying
3096 * truncation WAL records logged here.
3097 *
3098 * newOldestMulti is the oldest currently required multixact, newOldestMultiDB
3099 * is one of the databases preventing newOldestMulti from increasing.
3100 */
3101 void
3103 {
3104 MultiXactId oldestMulti;
3105 MultiXactId nextMulti;
3106 MultiXactOffset newOldestOffset;
3107 MultiXactOffset oldestOffset;
3108 MultiXactOffset nextOffset;
3109 mxtruncinfo trunc;
3110 MultiXactId earliest;
3115 /*
3116 * We can only allow one truncation to happen at once. Otherwise parts of
3117 * members might vanish while we're doing lookups or similar. There's no
3118 * need to have an interlock with creating new multis or such, since those
3119 * are constrained by the limits (which only grow, never shrink).
3120 */
3130 /*
3131 * Make sure to only attempt truncation if there's values to truncate
3132 * away. In normal processing values shouldn't go backwards, but there's
3133 * some corner cases (due to bugs) where that's possible.
3134 */
3136 {
3139 }
3141 /*
3142 * Note we can't just plow ahead with the truncation; it's possible that
3143 * there are no segments to truncate, which is a problem because we are
3144 * going to attempt to read the offsets page to determine where to
3145 * truncate the members SLRU. So we first scan the directory to determine
3146 * the earliest offsets page number that we can read without error.
3147 *
3148 * When nextMXact is less than one segment away from multiWrapLimit,
3149 * SlruScanDirCbFindEarliest can find some early segment other than the
3150 * actual earliest. (MultiXactOffsetPagePrecedes(EARLIEST, LATEST)
3151 * returns false, because not all pairs of entries have the same answer.)
3152 * That can also arise when an earlier truncation attempt failed unlink()
3153 * or returned early from this function. The only consequence is
3154 * returning early, which wastes space that we could have liberated.
3155 *
3156 * NB: It's also possible that the page that oldestMulti is on has already
3157 * been truncated away, and we crashed before updating oldestMulti.
3158 */
3165 /* If there's nothing to remove, we can bail out early. */
3167 {
3170 }
3172 /*
3173 * First, compute the safe truncation point for MultiXactMember. This is
3174 * the starting offset of the oldest multixact.
3175 *
3176 * Hopefully, find_multixact_start will always work here, because we've
3177 * already checked that it doesn't precede the earliest MultiXact on disk.
3178 * But if it fails, don't truncate anything, and log a message.
3179 */
3181 {
3182 /* there are NO MultiXacts */
3184 }
3186 {
3192 }
3194 /*
3195 * Secondly compute up to where to truncate. Lookup the corresponding
3196 * member offset for newOldestMulti for that.
3197 */
3199 {
3200 /* there are NO MultiXacts */
3202 }
3204 {
3206 (errmsg("cannot truncate up to MultiXact %u because it does not exist on disk, skipping truncation",
3207 newOldestMulti)));
3210 }
3213 "offsets [%u, %u), offsets segments [%llx, %llx), "
3222 /*
3223 * Do truncation, and the WAL logging of the truncation, in a critical
3224 * section. That way offsets/members cannot get out of sync anymore, i.e.
3225 * once consistent the newOldestMulti will always exist in members, even
3226 * if we crashed in the wrong moment.
3227 */
3230 /*
3231 * Prevent checkpoints from being scheduled concurrently. This is critical
3232 * because otherwise a truncation record might not be replayed after a
3233 * crash/basebackup, even though the state of the data directory would
3234 * require it.
3235 */
3239 /* WAL log truncation */
3244 /*
3245 * Update in-memory limits before performing the truncation, while inside
3246 * the critical section: Have to do it before truncation, to prevent
3247 * concurrent lookups of those values. Has to be inside the critical
3248 * section as otherwise a future call to this function would error out,
3249 * while looking up the oldest member in offsets, if our caller crashes
3250 * before updating the limits.
3251 */
3257 /* First truncate members */
3260 /* Then offsets */
3267 }
3269 /*
3270 * Decide whether a MultiXactOffset page number is "older" for truncation
3271 * purposes. Analogous to CLOGPagePrecedes().
3272 *
3273 * Offsetting the values is optional, because MultiXactIdPrecedes() has
3274 * translational symmetry.
3275 */
3276 static bool
3278 {
3279 MultiXactId multi1;
3280 MultiXactId multi2;
3290 }
3292 /*
3293 * Decide whether a MultiXactMember page number is "older" for truncation
3294 * purposes. There is no "invalid offset number" so use the numbers verbatim.
3295 */
3296 static bool
3298 {
3299 MultiXactOffset offset1;
3300 MultiXactOffset offset2;
3308 }
3310 /*
3311 * Decide which of two MultiXactIds is earlier.
3312 *
3313 * XXX do we need to do something special for InvalidMultiXactId?
3314 * (Doesn't look like it.)
3315 */
3316 bool
3318 {
3322 }
3324 /*
3325 * MultiXactIdPrecedesOrEquals -- is multi1 logically <= multi2?
3326 *
3327 * XXX do we need to do something special for InvalidMultiXactId?
3328 * (Doesn't look like it.)
3329 */
3330 bool
3332 {
3336 }
3339 /*
3340 * Decide which of two offsets is earlier.
3341 */
3342 static bool
3344 {
3348 }
3350 /*
3351 * Write an xlog record reflecting the zeroing of either a MEMBERs or
3352 * OFFSETs page (info shows which)
3353 */
3354 static void
3356 {
3360 }
3362 /*
3363 * Write a TRUNCATE xlog record
3364 *
3365 * We must flush the xlog record to disk before returning --- see notes in
3366 * TruncateCLOG().
3367 */
3368 static void
3372 {
3373 XLogRecPtr recptr;
3374 xl_multixact_truncate xlrec;
3388 }
3390 /*
3391 * MULTIXACT resource manager's routines
3392 */
3393 void
3395 {
3398 /* Backup blocks are not used in multixact records */
3402 {
3403 int64 pageno;
3417 }
3419 {
3420 int64 pageno;
3434 }
3436 {
3439 TransactionId max_xid;
3442 /* Store the data back into the SLRU files */
3446 /* Make sure nextMXact/nextOffset are beyond what this record has */
3450 /*
3451 * Make sure nextXid is beyond any XID mentioned in the record. This
3452 * should be unnecessary, since any XID found here ought to have other
3453 * evidence in the XLOG, but let's be safe.
3454 */
3457 {
3460 }
3463 }
3465 {
3466 xl_multixact_truncate xlrec;
3467 int64 pageno;
3470 SizeOfMultiXactTruncate);
3473 "offsets [%u, %u), offsets segments [%llx, %llx), "
3482 /* should not be required, but more than cheap enough */
3485 /*
3486 * Advance the horizon values, so they're current at the end of
3487 * recovery.
3488 */
3493 /*
3494 * During XLOG replay, latest_page_number isn't necessarily set up
3495 * yet; insert a suitable value to bypass the sanity test in
3496 * SimpleLruTruncate.
3497 */
3500 pageno);
3504 }
3505 else
3507 }
3509 Datum
3511 {
3513 {
3528 {
3529 MemoryContext oldcxt;
3530 TupleDesc tupdesc;
3536 /* no need to allow for old values here */
3548 }
3554 {
3555 HeapTuple tuple;
3566 }
3569 }
3571 /*
3572 * Entrypoint for sync.c to sync offsets files.
3573 */
3574 int
3576 {
3578 }
3580 /*
3581 * Entrypoint for sync.c to sync members files.
3582 */
3583 int
3585 {
3587 }