From f98dbdeb51d1175c07258cd2bd4b56f560dfc3cf Mon Sep 17 00:00:00 2001 From: Michael Paquier Date: Fri, 5 Apr 2024 08:56:52 +0900 Subject: [PATCH] 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 --- .../activity/generate-wait_event_types.pl | 28 ++++++++++++++++++- .../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.