postgres.git / summary / log / commit / refs
commit f98dbdeb51d1175c07258cd2bd4b56f560dfc3cf
Author: Michael Paquier <michael@paquier.xyz>
Date: Thu Apr 04 23:56:52 2024 +0000
First released in: 17.0
Add "ABI_compatibility" regions to wait_event_names.txt
The current design behind the automatic generation of the C code and
documentation related to wait events introduced in fa88928470b5 does not
offer a way to attach new wait events without breaking ABI
compatibility, as all the events are forcibly reordered for each section
in the input file wait_event_names.txt. Adding new wait events to
stable branches is something that has happened in the past, 0b6517a3b79a
being a recent example of that with VERSION_FILE_SYNC, so we need a way
to generate any C code for wait events while maintaining compatibility
on stable branches already released.
This commit solves this issue by adding a new region called
"ABI_compatibility" (keyword could be updated to something else if
someone had a better idea) to each section of wait_event_names.txt, so
as one can add new wait events to stable branches in
wait_event_names.txt while keeping the code ABI-compatible.
"ABI_compatibility" has no impact on the documentation generated: all
the wait events of one section are still alphabetically ordered. LWLock
and Lock sections generate their C code elsewhere, so they do not need
an "ABI_compatibility" region.
For example, let's imagine a wait_event_names.txt like that:
Section: ClassName - Foo
FOO_1 "Waiting in Foo 1"
FOO_2 "Waiting in Foo 2"
ABI_compatibility:
NEW_FOO_1 "Waiting in New Foo 1"
NEW_BAR_1 "Waiting in New Bar 1"
This results in the following enum, where the events in the ABI region
are listed last with the same ordering as in wait_event_names.txt:
typedef enum
{
WAIT_EVENT_FOO_1,
WAIT_EVENT_FOO_2,
WAIT_EVENT_NEW_FOO_1,
WAIT_EVENT_NEW_BAR_1
} WaitEventFoo;
New wait events added in stable branches should be added at the end of
each ABI_compatibility region, and ABI_compatibility should remain empty
on HEAD and unreleased stable branches.
This design has been suggested by Noah Misch and me.
Reported-by: Noah Misch
Author: Bertrand Drouvot
Reviewed-by: Michael Paquier
Discussion: https://postgr.es/m/20240317183114.16@rfd.leadboat.com
.../utils/activity/generate-wait_event_types.pl | 28 +++++++++++++++++++++-
src/backend/utils/activity/wait_event_names.txt | 18 ++++++++++++++
2 files changed, 45 insertions(+), 1 deletion(-)
diff --git a/src/backend/utils/activity/generate-wait_event_types.pl b/src/backend/utils/activity/generate-wait_event_types.pl
index f1adf0e8e74..42f36f405bd 100644
--- a/src/backend/utils/activity/generate-wait_event_types.pl
+++ b/src/backend/utils/activity/generate-wait_event_types.pl
@@ -38,7 +38,9 @@ die "Not possible to specify --docs and --code simultaneously"
open my $wait_event_names, '<', $ARGV[0] or die;
+my @abi_compatibility_lines;
my @lines;
+my $abi_compatibility = 0;
my $section_name;
my $note;
my $note_name;
@@ -59,10 +61,27 @@ while (<$wait_event_names>)
{
$section_name = $_;
$section_name =~ s/^.*- //;
+ $abi_compatibility = 0;
next;
}
- push(@lines, $section_name . "\t" . $_);
+ # ABI_compatibility region, preserving ABI compatibility of the code
+ # generated. Any wait events listed in this part of the file will
+ # not be sorted during the code generation.
+ if (/^ABI_compatibility:$/)
+ {
+ $abi_compatibility = 1;
+ next;
+ }
+
+ if ($gen_code && $abi_compatibility)
+ {
+ push(@abi_compatibility_lines, $section_name . "\t" . $_);
+ }
+ else
+ {
+ push(@lines, $section_name . "\t" . $_);
+ }
}
# Sort the lines based on the second column.
@@ -70,6 +89,13 @@ while (<$wait_event_names>)
my @lines_sorted =
sort { uc((split(/\t/, $a))[1]) cmp uc((split(/\t/, $b))[1]) } @lines;
+# If we are generating code, concat @lines_sorted and then
+# @abi_compatibility_lines.
+if ($gen_code)
+{
+ push(@lines_sorted, @abi_compatibility_lines);
+}
+
# Read the sorted lines and populate the hash table
foreach my $line (@lines_sorted)
{
diff --git a/src/backend/utils/activity/wait_event_names.txt b/src/backend/utils/activity/wait_event_names.txt
index 0d288d6b3d8..39a1c40d76c 100644
--- a/src/backend/utils/activity/wait_event_names.txt
+++ b/src/backend/utils/activity/wait_event_names.txt
@@ -26,6 +26,13 @@
# When adding a new wait event, make sure it is placed in the appropriate
# ClassName section.
#
+# Wait events added in stable branches should be appended to the lists in
+# the "ABI_compatibility:" region of their related ClassName section to
+# preserve ABI compatibility of the C code generated from this file's data,
+# respecting the order of any wait event already listed there. The
+# "ABI_compatibility:" regions should remain empty on the master branch and
+# on unreleased branches.
+#
# WaitEventLWLock and WaitEventLock have their own C code for their wait event
# enums and function names. Hence, for these, only the SGML documentation is
# generated.
@@ -61,6 +68,7 @@ WAL_SENDER_MAIN "Waiting in main loop of WAL sender process."
WAL_SUMMARIZER_WAL "Waiting in WAL summarizer for more WAL to be generated."
WAL_WRITER_MAIN "Waiting in main loop of WAL writer process."
+ABI_compatibility:
#
# Wait Events - Client
@@ -83,6 +91,7 @@ WAIT_FOR_WAL_REPLAY "Waiting for a replay of the particular WAL position on the
WAL_SENDER_WAIT_FOR_WAL "Waiting for WAL to be flushed in WAL sender process."
WAL_SENDER_WRITE_DATA "Waiting for any activity when processing replies from WAL receiver in WAL sender process."
+ABI_compatibility:
#
# Wait Events - IPC
@@ -150,6 +159,7 @@ WAL_RECEIVER_WAIT_START "Waiting for startup process to send initial data for st
WAL_SUMMARY_READY "Waiting for a new WAL summary to be generated."
XACT_GROUP_UPDATE "Waiting for the group leader to update transaction status at end of a parallel operation."
+ABI_compatibility:
#
# Wait Events - Timeout
@@ -170,6 +180,7 @@ VACUUM_DELAY "Waiting in a cost-based vacuum delay point."
VACUUM_TRUNCATE "Waiting to acquire an exclusive lock to truncate off any empty pages at the end of a table vacuumed."
WAL_SUMMARIZER_ERROR "Waiting after a WAL summarizer error."
+ABI_compatibility:
#
# Wait Events - IO
@@ -257,6 +268,7 @@ WAL_SYNC "Waiting for a WAL file to reach durable storage."
WAL_SYNC_METHOD_ASSIGN "Waiting for data to reach durable storage while assigning a new WAL sync method."
WAL_WRITE "Waiting for a write to a WAL file."
+ABI_compatibility:
#
# Wait Events - Buffer Pin
@@ -266,6 +278,7 @@ Section: ClassName - WaitEventBufferPin
BUFFER_PIN "Waiting to acquire an exclusive pin on a buffer."
+ABI_compatibility:
#
# Wait Events - Extension
@@ -275,6 +288,8 @@ Section: ClassName - WaitEventExtension
Extension "Waiting in an extension."
+ABI_compatibility:
+
#
# Wait Events - LWLock
#
@@ -379,6 +394,7 @@ SubtransSLRU "Waiting to access the sub-transaction SLRU cache."
XactSLRU "Waiting to access the transaction status SLRU cache."
ParallelVacuumDSA "Waiting for parallel vacuum dynamic shared memory allocation."
+# No "ABI_compatibility" region here as WaitEventLWLock has its own C code.
#
# Wait Events - Lock
@@ -401,3 +417,5 @@ object "Waiting to acquire a lock on a non-relation database object."
userlock "Waiting to acquire a user lock."
advisory "Waiting to acquire an advisory user lock."
applytransaction "Waiting to acquire a lock on a remote transaction being applied by a logical replication subscriber."
+
+# No "ABI_compatibility" region here as WaitEventLock has its own C code.
[parent: e2a235767180]