From 33b75d4b745e2a6d3a19360b9143fa05aa28708c Mon Sep 17 00:00:00 2001 From: Zhiguo Zhou Date: Sat, 10 Oct 2026 15:50:45 +0800 Subject: [PATCH v1] Make the number of WAL insertion locks configurable Add wal_insert_locks as a startup setting, defaulting to 8. Accept powers of two from 4 to 128, and use it to size the shared lock array and select insertion locks. Release locks in reverse acquisition order. Document the tradeoff between insertion concurrency and the cost of waiting for insertions and reserving WAL space. Add tests for valid and invalid settings, concurrent insertion, segment switches and recovery. Reviewed-by: Andrew Kim Tested-by: Andrew Kim --- doc/src/sgml/config.sgml | 28 +++++++ src/backend/access/transam/xlog.c | 52 ++++++++---- src/backend/utils/misc/guc_parameters.dat | 10 +++ src/backend/utils/misc/postgresql.conf.sample | 2 + src/include/access/xlog.h | 1 + src/include/utils/guc_hooks.h | 1 + src/test/modules/test_misc/meson.build | 1 + .../test_misc/t/016_wal_insert_locks.pl | 84 +++++++++++++++++++ 8 files changed, 163 insertions(+), 16 deletions(-) create mode 100644 src/test/modules/test_misc/t/016_wal_insert_locks.pl diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index 886e8c44847..044f8cdfaa7 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -3769,6 +3769,34 @@ include_dir 'conf.d' + + wal_insert_locks (integer) + + wal_insert_locks configuration parameter + + + + + Sets the number of lightweight locks used for inserting records into + the WAL buffers. Each inserting backend holds one lock while copying + its record. More locks allow more concurrent insertions, which can + improve throughput on systems with many CPU cores. The default is 8. + The value must be a power of two between 4 and 128. This parameter can + only be set at server start. + + + + Waiting for WAL insertions to finish, for example before flushing WAL, + requires checking all insertion locks. More locks increase this cost + and can also increase contention during WAL space reservation, + especially on builds that use a spinlock for reservation. Increasing + this setting can reduce throughput; test it with a representative + workload. + + + + + wal_writer_delay (integer) diff --git a/src/backend/access/transam/xlog.c b/src/backend/access/transam/xlog.c index 4738a3ea2e3..f352d87c41d 100644 --- a/src/backend/access/transam/xlog.c +++ b/src/backend/access/transam/xlog.c @@ -150,11 +150,11 @@ bool XLOG_DEBUG = false; int wal_segment_size = DEFAULT_XLOG_SEG_SIZE; /* - * Number of WAL insertion locks to use. A higher value allows more insertions - * to happen concurrently, but adds some CPU overhead to flushing the WAL, - * which needs to iterate all the locks. + * Number of WAL insertion locks, set at startup by wal_insert_locks. More + * locks allow more concurrent insertions, but make flushing WAL more costly + * since it must scan all locks. Require a power of two for bitmask selection. */ -#define NUM_XLOGINSERT_LOCKS 8 +int num_xloginsert_locks = 8; /* * Max distance from last checkpoint, before triggering a new xlog-based @@ -922,7 +922,7 @@ XLogInsertRecord(XLogRecData *rdata, * inserter acquires an insertion lock. In addition to just indicating that * an insertion is in progress, the lock tells others how far the inserter * has progressed. There is a small fixed number of insertion locks, - * determined by NUM_XLOGINSERT_LOCKS. When an inserter crosses a page + * determined by num_xloginsert_locks. When an inserter crosses a page * boundary, it updates the value stored in the lock to the how far it has * inserted, to allow the previous buffer to be flushed. * @@ -1572,8 +1572,9 @@ WALInsertLockAcquire(void) */ static int lockToTry = -1; + /* num_xloginsert_locks is a power of two, so modulo is a bitmask */ if (lockToTry == -1) - lockToTry = MyProcNumber % NUM_XLOGINSERT_LOCKS; + lockToTry = MyProcNumber & (num_xloginsert_locks - 1); MyLockNo = lockToTry; /* @@ -1591,7 +1592,7 @@ WALInsertLockAcquire(void) * than locks, it still helps to distribute the inserters evenly * across the locks. */ - lockToTry = (lockToTry + 1) % NUM_XLOGINSERT_LOCKS; + lockToTry = (lockToTry + 1) & (num_xloginsert_locks - 1); } } @@ -1609,7 +1610,7 @@ WALInsertLockAcquireExclusive(void) * indicator is set to 0xFFFFFFFFFFFFFFFF, which is higher than any real * XLogRecPtr value, to make sure that no-one blocks waiting on those. */ - for (i = 0; i < NUM_XLOGINSERT_LOCKS - 1; i++) + for (i = 0; i < num_xloginsert_locks - 1; i++) { LWLockAcquire(&WALInsertLocks[i].l.lock, LW_EXCLUSIVE); LWLockUpdateVar(&WALInsertLocks[i].l.lock, @@ -1635,7 +1636,11 @@ WALInsertLockRelease(void) { int i; - for (i = 0; i < NUM_XLOGINSERT_LOCKS; i++) + /* + * Release in reverse acquisition order to avoid searches through + * held_lwlocks in LWLockRelease. + */ + for (i = num_xloginsert_locks - 1; i >= 0; i--) LWLockReleaseClearVar(&WALInsertLocks[i].l.lock, &WALInsertLocks[i].l.insertingAt, 0); @@ -1663,8 +1668,8 @@ WALInsertLockUpdateInsertingAt(XLogRecPtr insertingAt) * We use the last lock to mark our actual position, see comments in * WALInsertLockAcquireExclusive. */ - LWLockUpdateVar(&WALInsertLocks[NUM_XLOGINSERT_LOCKS - 1].l.lock, - &WALInsertLocks[NUM_XLOGINSERT_LOCKS - 1].l.insertingAt, + LWLockUpdateVar(&WALInsertLocks[num_xloginsert_locks - 1].l.lock, + &WALInsertLocks[num_xloginsert_locks - 1].l.insertingAt, insertingAt); } else @@ -1738,7 +1743,7 @@ WaitXLogInsertionsToFinish(XLogRecPtr upto) * out for any insertion that's still in progress. */ finishedUpto = reservedUpto; - for (i = 0; i < NUM_XLOGINSERT_LOCKS; i++) + for (i = 0; i < num_xloginsert_locks; i++) { XLogRecPtr insertingat = InvalidXLogRecPtr; @@ -5381,6 +5386,21 @@ check_wal_buffers(int *newval, void **extra, GucSource source) return true; } +/* + * GUC check_hook for wal_insert_locks. The range is checked by the GUC code; + * require a power of two here so lock selection can use a bitmask. + */ +bool +check_wal_insert_locks(int *newval, void **extra, GucSource source) +{ + if ((*newval & (*newval - 1)) != 0) + { + GUC_check_errdetail("\"wal_insert_locks\" must be a power of two."); + return false; + } + return true; +} + /* * GUC check_hook for wal_consistency_checking */ @@ -5636,7 +5656,7 @@ XLOGShmemRequest(void *arg) size = sizeof(XLogCtlData); /* WAL insertion locks, plus alignment */ - size = add_size(size, mul_size(sizeof(WALInsertLockPadded), NUM_XLOGINSERT_LOCKS + 1)); + size = add_size(size, mul_size(sizeof(WALInsertLockPadded), num_xloginsert_locks + 1)); /* xlblocks array */ size = add_size(size, mul_size(sizeof(pg_atomic_uint64), XLOGbuffers)); /* extra alignment padding for XLOG I/O buffers */ @@ -5695,9 +5715,9 @@ XLOGShmemInit(void *arg) ((uintptr_t) allocptr) % sizeof(WALInsertLockPadded); WALInsertLocks = XLogCtl->Insert.WALInsertLocks = (WALInsertLockPadded *) allocptr; - allocptr += sizeof(WALInsertLockPadded) * NUM_XLOGINSERT_LOCKS; + allocptr += sizeof(WALInsertLockPadded) * num_xloginsert_locks; - for (i = 0; i < NUM_XLOGINSERT_LOCKS; i++) + for (i = 0; i < num_xloginsert_locks; i++) { LWLockInitialize(&WALInsertLocks[i].l.lock, LWTRANCHE_WAL_INSERT); pg_atomic_init_u64(&WALInsertLocks[i].l.insertingAt, InvalidXLogRecPtr); @@ -7452,7 +7472,7 @@ GetLastImportantRecPtr(void) XLogRecPtr res = InvalidXLogRecPtr; int i; - for (i = 0; i < NUM_XLOGINSERT_LOCKS; i++) + for (i = 0; i < num_xloginsert_locks; i++) { XLogRecPtr last_important; diff --git a/src/backend/utils/misc/guc_parameters.dat b/src/backend/utils/misc/guc_parameters.dat index 184fcf49080..f4fa68ff676 100644 --- a/src/backend/utils/misc/guc_parameters.dat +++ b/src/backend/utils/misc/guc_parameters.dat @@ -3518,6 +3518,16 @@ boot_val => 'true', }, +{ name => 'wal_insert_locks', type => 'int', context => 'PGC_POSTMASTER', group => 'WAL_SETTINGS', + short_desc => 'Sets the number of WAL insertion locks.', + long_desc => 'A higher value allows more WAL insertions to proceed concurrently on high-core-count systems. Must be a power of two.', + variable => 'num_xloginsert_locks', + boot_val => '8', + min => '4', + max => '128', + check_hook => 'check_wal_insert_locks', +}, + { name => 'wal_keep_size', type => 'int', context => 'PGC_SIGHUP', group => 'REPLICATION_SENDING', short_desc => 'Sets the size of WAL files held for standby servers.', flags => 'GUC_UNIT_MB', diff --git a/src/backend/utils/misc/postgresql.conf.sample b/src/backend/utils/misc/postgresql.conf.sample index b492b3af06c..926077e748d 100644 --- a/src/backend/utils/misc/postgresql.conf.sample +++ b/src/backend/utils/misc/postgresql.conf.sample @@ -268,6 +268,8 @@ #wal_recycle = on # recycle WAL files #wal_buffers = -1 # min 32kB, -1 sets based on shared_buffers # (change requires restart) +#wal_insert_locks = 8 # power of 2, between 4 and 128 + # (change requires restart) #wal_writer_delay = 200ms # 1-10000 milliseconds #wal_writer_flush_after = 1MB # measured in pages, 0 disables #wal_skip_threshold = 2MB diff --git a/src/include/access/xlog.h b/src/include/access/xlog.h index 2bf5714b51e..3d5a92a2ef5 100644 --- a/src/include/access/xlog.h +++ b/src/include/access/xlog.h @@ -41,6 +41,7 @@ extern PGDLLIMPORT int max_wal_size_mb; extern PGDLLIMPORT int wal_keep_size_mb; extern PGDLLIMPORT int max_slot_wal_keep_size_mb; extern PGDLLIMPORT int XLOGbuffers; +extern PGDLLIMPORT int num_xloginsert_locks; extern PGDLLIMPORT int XLogArchiveTimeout; extern PGDLLIMPORT int wal_retrieve_retry_interval; extern PGDLLIMPORT char *XLogArchiveCommand; diff --git a/src/include/utils/guc_hooks.h b/src/include/utils/guc_hooks.h index 8e3c067f760..cbd5ff06342 100644 --- a/src/include/utils/guc_hooks.h +++ b/src/include/utils/guc_hooks.h @@ -169,6 +169,7 @@ extern bool check_transaction_isolation(int *newval, void **extra, GucSource sou extern bool check_transaction_read_only(bool *newval, void **extra, GucSource source); extern void assign_transaction_timeout(int newval, void *extra); extern bool check_wal_buffers(int *newval, void **extra, GucSource source); +extern bool check_wal_insert_locks(int *newval, void **extra, GucSource source); extern bool check_wal_consistency_checking(char **newval, void **extra, GucSource source); extern void assign_wal_consistency_checking(const char *newval, void *extra); diff --git a/src/test/modules/test_misc/meson.build b/src/test/modules/test_misc/meson.build index 5225aa280ca..5cf207e3bf6 100644 --- a/src/test/modules/test_misc/meson.build +++ b/src/test/modules/test_misc/meson.build @@ -25,6 +25,7 @@ tests += { 't/014_log_statement_max_length.pl', 't/015_temp_schema_exit_deferrable.pl', 't/016_heap_scan_stream.pl', + 't/016_wal_insert_locks.pl', ], # The injection points are cluster-wide, so disable installcheck 'runningcheck': false, diff --git a/src/test/modules/test_misc/t/016_wal_insert_locks.pl b/src/test/modules/test_misc/t/016_wal_insert_locks.pl new file mode 100644 index 00000000000..706b43a3792 --- /dev/null +++ b/src/test/modules/test_misc/t/016_wal_insert_locks.pl @@ -0,0 +1,84 @@ +# Copyright (c) 2024-2026, PostgreSQL Global Development Group + +# Tests for the wal_insert_locks GUC: a valid non-default power-of-two value +# works under WAL-generating activity, and an in-range non-power-of-two value +# is rejected at server start by the check hook. + +use strict; +use warnings FATAL => 'all'; +use PostgreSQL::Test::Cluster; +use PostgreSQL::Test::Utils; +use Test::More; + +# A valid, non-default, power-of-two value is accepted and exercised. +my $node = PostgreSQL::Test::Cluster->new('main'); +$node->init; +$node->append_conf('postgresql.conf', 'wal_insert_locks = 16'); +$node->start; + +is($node->safe_psql('postgres', 'SHOW wal_insert_locks'), + '16', 'non-default power-of-two wal_insert_locks is accepted'); + +# Generate WAL to exercise the reservation/insertion path with the +# non-default lock count. +$node->safe_psql('postgres', + 'CREATE TABLE t (id int); INSERT INTO t SELECT generate_series(1, 100000);' +); +is($node->safe_psql('postgres', 'SELECT count(*) FROM t'), + '100000', 'WAL-generating activity works with a non-default lock count'); +$node->stop; + +# An in-range but non-power-of-two value must be rejected at startup. +my $bad = PostgreSQL::Test::Cluster->new('bad'); +$bad->init; +$bad->append_conf('postgresql.conf', 'wal_insert_locks = 12'); +my $started = $bad->start(fail_ok => 1); +ok(!$started, + 'server refuses to start with a non-power-of-two wal_insert_locks'); +like( + slurp_file($bad->logfile), + qr/must be a power of two/, + 'startup failure reports the power-of-two requirement'); + +# Exercise both ends of the allowed range, including operations that hold +# all insertion locks and recovery with a non-default lock count. +my $expected_rows = 100000; +for my $locks (4, 128) +{ + $node->append_conf('postgresql.conf', "wal_insert_locks = $locks"); + $node->start; + is($node->safe_psql('postgres', 'SHOW wal_insert_locks'), + "$locks", "wal_insert_locks = $locks is accepted"); + $node->safe_psql('postgres', 'CHECKPOINT'); + $node->pgbench( + '--no-vacuum --client=16 --transactions=20', + 0, + [], + [], + "concurrent inserts with wal_insert_locks = $locks", + { "locks_$locks.sql" => 'INSERT INTO t VALUES (1)' }); + $expected_rows += 320; + $node->safe_psql('postgres', 'SELECT pg_switch_wal()'); + $node->stop('immediate'); + $node->start; + is($node->safe_psql('postgres', 'SELECT count(*) FROM t'), + "$expected_rows", + "rows survive restart with wal_insert_locks = $locks"); + $node->stop; +} + +# Values outside the GUC range must also be rejected. +for my $locks (2, 256) +{ + $node->command_fails_like( + [ + 'postgres', '-D', + $node->data_dir, '-C', + 'wal_insert_locks', '-c', + "wal_insert_locks=$locks" + ], + qr/outside the valid range/, + "wal_insert_locks = $locks is out of range"); +} + +done_testing();