Slru Infrastructure

slru-infrastructure — the fixed-page cache under CLOG / MultiXact / others

PostgreSQL has FIVE places where it needs a small, contention-friendly cache for status data indexed by monotonically-increasing IDs:

• CLOG (pg_xact/) — 2 bits per XID (in-progress / committed / aborted / subcommitted). Under access/transam/clog.c.
• MultiXact offsets + members (pg_multixact/{offsets,members}/) — 2 separate SLRUs for the tuple-locking machinery. Under access/transam/multixact.c.
• Subtrans (pg_subtrans/) — subtransaction xid → parent xid mapping. Under access/transam/subtrans.c.
• CommitTs (pg_commit_ts/) — per-xid commit timestamp (if track_commit_timestamp = on). Under access/transam/commit_ts.c.
• Notify (pg_notify/) — LISTEN/NOTIFY queue. Under commands/async.c.

Each COULD have used the main shared-buffer pool, but SLRU is optimized for the specific "small, always-hot, indexed by ID" pattern with a much cheaper per-page lock design.

The file

Single-file infrastructure:

• src/backend/access/transam/slru.c (~1400 lines) — the whole implementation.
• src/include/access/slru.h — the SlruCtl struct + public API.

The design — bank-locked LRU

Each SLRU has:

• N in-memory pages (typically 8-128, configurable).
• Banks — groups of pages sharing a lock. PG 17+ increased banks + made per-SLRU sizing GUC-configurable.
• LRU counters per page.
• Dirty flag per page.
• Latest-page pin — the page for the highest ID is always pinned (the write frontier).

Reading a page:

1. Check if it's in cache. Take the bank lock (SHARED).
2. If cached: touch the LRU counter + return.
3. If not: promote lock to EXCLUSIVE, evict the LRU page (flush if dirty), read from disk.

The bank-lock structure means many concurrent readers hit different banks with no contention. Vs shared_buffers where every page has a header hot-lock, SLRU wins on this specific access pattern.

The on-disk file layout

Each SLRU stores its data in pg_<name>/ directory as fixed-size segment files:

• 32 pages per segment (default; some SLRUs override).
• Segment file names are hex — e.g. pg_xact/0000 is segments 0-31.
• Individual pages are 8 KB.
• Truncation at boundaries — the oldest segment gets removed after ALL its IDs are no longer needed.

Truncation is what enables SLRU wraparound: as long as VACUUM keeps oldestXid (or oldestMulti etc.) moving forward, older segments get pruned.

The SlruCtl struct

Each SLRU consumer registers with a SlruCtl (control) struct at startup:

• Directory name (pg_xact etc.).
• Number of buffers.
• Number of banks.
• Bank lock names.
• LWLock tranche ID.
• Reference to shmem area for the page arrays.
• PagePrecedes callback — the ID-ordering function (some SLRUs use forward XIDs, some use MultiXact IDs — they may have different wrap semantics).

Reading and writing

/* Read */
int slotno = SimpleLruReadPage(SlruCtl, pageno, ok_if_not_found, xid);
if (slotno == -1) ereport(...);
/* Access shared->page_buffer[slotno] with the bank lock held share. */

/* Write */
int slotno = SimpleLruReadPage_ReadOnly(SlruCtl, pageno, xid);
/* Modify shared->page_buffer[slotno]. */
SimpleLruWritePage(SlruCtl, slotno);

Actual reads/writes are LWLock-protected but not WAL-logged in the hot path (except for MultiXact members, which have their own WAL discipline). The persistence guarantee comes from checkpointing.

Per-SLRU GUC-tuning (PG 17+)

Before PG 17, SLRU sizes were compile-time constants. PG 17 made them runtime-configurable:

• commit_timestamp_buffers
• multixact_offset_buffers / multixact_member_buffers
• notify_buffers
• serializable_buffers
• subtransaction_buffers
• transaction_buffers

Each GUC controls the number of pages in that SLRU's cache. Default depends on the SLRU (typically 8-64). On high-transaction-rate systems, bumping these helps significantly.

Common patch shapes

Add a new SLRU consumer

• Define SlruCtl <name>Ctl at file scope.
• In shmem init: SimpleLruInit(<name>Ctl, "NameForLog", num_buffers, num_banks, LWLockTrancheId, "pg_yourname", ...).
• Register directory pg_yourname/ in initdb (via RelationInitPhysicalAddr or similar).
• Implement PagePrecedes for ID ordering.
• Set up read/write helpers using SimpleLruReadPage / SimpleLruWritePage.
• WAL / crash-recovery: consider whether this SLRU needs to be truncated at recovery.
• Regress + TAP tests for wraparound behavior.

Add a new GUC for existing SLRU sizing

• New GUC constant in guc_tables.c.
• Pass to SimpleLruInit at shmem-init time.
• Add to per-cluster tuning docs.

Debug SLRU pressure

• pg_stat_slru (in pgstat_slru.c) — per-SLRU counters: blks_zeroed, blks_hit, blks_read, blks_written, blks_exists, flushes, truncates.
• High read counter → cache thrash; increase buffers for that SLRU.
• High flushes counter → concurrent writes competing; increase banks or buffers.

Add SLRU write coalescing

Uncommon. Would touch the individual write coalescer per SLRU consumer.

Pitfalls

• SLRU pages are 8 KB — same as main pages but NOT the same address space — a bufmgr Buffer number won't work with SLRU. Different infrastructure.
• Truncation moves the oldest boundary forward — a code path that STILL needs an old page (e.g., logical replication needing an old CLOG entry for an old xmin) will error. This is why long-running logical slots pin catalog_xmin.
• PagePrecedes must handle wraparound — 32-bit ID wraparound means "smaller" changes meaning around the wrap point. Getting this wrong = disaster.
• Read-only pages held across long operations block writes — SLRU is designed for short-lived pins. Extension code that holds a page across long queries can starve the write side.
• Per-SLRU GUCs aren't backported — code assuming per-GUC configurable sizes doesn't compile on pre-PG-17.
• pg_stat_slru bytes are pages, not disk bytes — a common mistake in monitoring.
• SLRU segments are 256 KB (32×8KB) — very small compared to WAL segments. Manual pruning during recovery is rare.
• SimpleLruReadPage under EXCLUSIVE holds an LWLock across I/O — I/O time is included in the lock hold. A slow disk on the SLRU path hurts more than on shared buffers.
• CLOG hot path bypass — a common perf pattern is checking hint bits first + only calling into CLOG on miss. Because hint bits are per-tuple + lazy-updated, CLOG can be the perf floor.

Related corpus

• Idioms: slru-page-replacement (the bank-locked LRU design), clog-slru (CLOG-specific semantics), multixact-slru (MultiXact-specific), subxact-subtrans-slru (Subtrans), notify-listen-coordination (Notify SLRU usage).
• Subsystem: access-transam (parent of most SLRU consumers).
• Data structure: pgproc-fields (per-backend xmin/xmax feed into oldestXid computation which drives SLRU truncation).
• Skills: multixact (specific SLRU consumer).

Corpus-chain shortcut

python3 scripts/corpus-chain.py --idiom slru-page-replacement
python3 scripts/corpus-chain.py --file src/backend/access/transam/slru.c

Boundary

Use this skill for slru.c infrastructure + new-SLRU-consumer patches + SLRU GUC tuning.

Don't use for:

• Individual SLRU consumers' semantics — multixact skill for MultiXact, access-transam subsystem for CLOG / Subtrans / CommitTs semantics.
• shared_buffers — different cache. See buffer-manager.
• pg_notify/ queue semantics — LISTEN/NOTIFY has its own state machine; SLRU just provides the storage.
• CLOG hint bits (HEAP_XMIN_COMMITTED etc.) — those are tuple-level, not SLRU-cache-level.