database/postgres
database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-05-03 22:24:49 +03:00
Code

Add "ABI_compatibility" regions to wait_event_names.txt

Browse Source 
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
This commit is contained in:
Michael Paquier 2024-04-05 08:56:52 +09:00
parent e2a2357671
commit f98dbdeb51
2 changed files with 45 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
src/backend/utils/activity/generate-wait_event_types.pl
View File

@ -38,7 +38,9 @@ die "Not possible to specify --docs and --code simultaneously"
open my $wait_event_names, '<', $ARGV[0] or die; open my $wait_event_names, '<', $ARGV[0] or die;
my @abi_compatibility_lines;
my @lines; my @lines;
my $abi_compatibility = 0;
my $section_name; my $section_name;
my $note; my $note;
my $note_name; my $note_name;
@ -59,10 +61,27 @@ while (<$wait_event_names>)
{ {
$section_name = $_; $section_name = $_;
$section_name =~ s/^.*- //; $section_name =~ s/^.*- //;
$abi_compatibility = 0;
next; 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. # Sort the lines based on the second column.
@ -70,6 +89,13 @@ while (<$wait_event_names>)
my @lines_sorted = my @lines_sorted =
sort { uc((split(/\t/, $a))[1]) cmp uc((split(/\t/, $b))[1]) } @lines; 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 # Read the sorted lines and populate the hash table
foreach my $line (@lines_sorted) foreach my $line (@lines_sorted)
{ {

18
src/backend/utils/activity/wait_event_names.txt
View File

@ -26,6 +26,13 @@
# When adding a new wait event, make sure it is placed in the appropriate # When adding a new wait event, make sure it is placed in the appropriate
# ClassName section. # 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 # WaitEventLWLock and WaitEventLock have their own C code for their wait event
# enums and function names. Hence, for these, only the SGML documentation is # enums and function names. Hence, for these, only the SGML documentation is
# generated. # 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_SUMMARIZER_WAL "Waiting in WAL summarizer for more WAL to be generated."
WAL_WRITER_MAIN "Waiting in main loop of WAL writer process." WAL_WRITER_MAIN "Waiting in main loop of WAL writer process."
ABI_compatibility:
# #
# Wait Events - Client # 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_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." WAL_SENDER_WRITE_DATA "Waiting for any activity when processing replies from WAL receiver in WAL sender process."
ABI_compatibility:
# #
# Wait Events - IPC # 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." 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." XACT_GROUP_UPDATE "Waiting for the group leader to update transaction status at end of a parallel operation."
ABI_compatibility:
# #
# Wait Events - Timeout # 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." 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." WAL_SUMMARIZER_ERROR "Waiting after a WAL summarizer error."
ABI_compatibility:
# #
# Wait Events - IO # 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_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." WAL_WRITE "Waiting for a write to a WAL file."
ABI_compatibility:
# #
# Wait Events - Buffer Pin # Wait Events - Buffer Pin
@ -266,6 +278,7 @@ Section: ClassName - WaitEventBufferPin
BUFFER_PIN "Waiting to acquire an exclusive pin on a buffer." BUFFER_PIN "Waiting to acquire an exclusive pin on a buffer."
ABI_compatibility:
# #
# Wait Events - Extension # Wait Events - Extension
@ -275,6 +288,8 @@ Section: ClassName - WaitEventExtension
Extension "Waiting in an extension." Extension "Waiting in an extension."
ABI_compatibility:
# #
# Wait Events - LWLock # 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." XactSLRU "Waiting to access the transaction status SLRU cache."
ParallelVacuumDSA "Waiting for parallel vacuum dynamic shared memory allocation." ParallelVacuumDSA "Waiting for parallel vacuum dynamic shared memory allocation."
# No "ABI_compatibility" region here as WaitEventLWLock has its own C code.
# #
# Wait Events - Lock # 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." userlock "Waiting to acquire a user lock."
advisory "Waiting to acquire an advisory 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." 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.