Location via proxy:   [ UP ]  
[Report a bug]   [Manage cookies]                
Skip to content

Commit f98dbde

Browse files
committed
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 fa88928 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, 0b6517a 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
1 parent e2a2357 commit f98dbde

File tree

2 files changed

+45
-1
lines changed

2 files changed

+45
-1
lines changed

src/backend/utils/activity/generate-wait_event_types.pl

+27-1
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,9 @@
3838

3939
open my $wait_event_names, '<', $ARGV[0] or die;
4040

41+
my @abi_compatibility_lines;
4142
my @lines;
43+
my $abi_compatibility = 0;
4244
my $section_name;
4345
my $note;
4446
my $note_name;
@@ -59,17 +61,41 @@
5961
{
6062
$section_name = $_;
6163
$section_name =~ s/^.*- //;
64+
$abi_compatibility = 0;
6265
next;
6366
}
6467

65-
push(@lines, $section_name . "\t" . $_);
68+
# ABI_compatibility region, preserving ABI compatibility of the code
69+
# generated. Any wait events listed in this part of the file will
70+
# not be sorted during the code generation.
71+
if (/^ABI_compatibility:$/)
72+
{
73+
$abi_compatibility = 1;
74+
next;
75+
}
76+
77+
if ($gen_code && $abi_compatibility)
78+
{
79+
push(@abi_compatibility_lines, $section_name . "\t" . $_);
80+
}
81+
else
82+
{
83+
push(@lines, $section_name . "\t" . $_);
84+
}
6685
}
6786

6887
# Sort the lines based on the second column.
6988
# uc() is being used to force the comparison to be case-insensitive.
7089
my @lines_sorted =
7190
sort { uc((split(/\t/, $a))[1]) cmp uc((split(/\t/, $b))[1]) } @lines;
7291

92+
# If we are generating code, concat @lines_sorted and then
93+
# @abi_compatibility_lines.
94+
if ($gen_code)
95+
{
96+
push(@lines_sorted, @abi_compatibility_lines);
97+
}
98+
7399
# Read the sorted lines and populate the hash table
74100
foreach my $line (@lines_sorted)
75101
{

src/backend/utils/activity/wait_event_names.txt

+18
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,13 @@
2626
# When adding a new wait event, make sure it is placed in the appropriate
2727
# ClassName section.
2828
#
29+
# Wait events added in stable branches should be appended to the lists in
30+
# the "ABI_compatibility:" region of their related ClassName section to
31+
# preserve ABI compatibility of the C code generated from this file's data,
32+
# respecting the order of any wait event already listed there. The
33+
# "ABI_compatibility:" regions should remain empty on the master branch and
34+
# on unreleased branches.
35+
#
2936
# WaitEventLWLock and WaitEventLock have their own C code for their wait event
3037
# enums and function names. Hence, for these, only the SGML documentation is
3138
# generated.
@@ -61,6 +68,7 @@ WAL_SENDER_MAIN "Waiting in main loop of WAL sender process."
6168
WAL_SUMMARIZER_WAL "Waiting in WAL summarizer for more WAL to be generated."
6269
WAL_WRITER_MAIN "Waiting in main loop of WAL writer process."
6370

71+
ABI_compatibility:
6472

6573
#
6674
# Wait Events - Client
@@ -83,6 +91,7 @@ WAIT_FOR_WAL_REPLAY "Waiting for a replay of the particular WAL position on the
8391
WAL_SENDER_WAIT_FOR_WAL "Waiting for WAL to be flushed in WAL sender process."
8492
WAL_SENDER_WRITE_DATA "Waiting for any activity when processing replies from WAL receiver in WAL sender process."
8593

94+
ABI_compatibility:
8695

8796
#
8897
# Wait Events - IPC
@@ -150,6 +159,7 @@ WAL_RECEIVER_WAIT_START "Waiting for startup process to send initial data for st
150159
WAL_SUMMARY_READY "Waiting for a new WAL summary to be generated."
151160
XACT_GROUP_UPDATE "Waiting for the group leader to update transaction status at end of a parallel operation."
152161

162+
ABI_compatibility:
153163

154164
#
155165
# Wait Events - Timeout
@@ -170,6 +180,7 @@ VACUUM_DELAY "Waiting in a cost-based vacuum delay point."
170180
VACUUM_TRUNCATE "Waiting to acquire an exclusive lock to truncate off any empty pages at the end of a table vacuumed."
171181
WAL_SUMMARIZER_ERROR "Waiting after a WAL summarizer error."
172182

183+
ABI_compatibility:
173184

174185
#
175186
# Wait Events - IO
@@ -257,6 +268,7 @@ WAL_SYNC "Waiting for a WAL file to reach durable storage."
257268
WAL_SYNC_METHOD_ASSIGN "Waiting for data to reach durable storage while assigning a new WAL sync method."
258269
WAL_WRITE "Waiting for a write to a WAL file."
259270

271+
ABI_compatibility:
260272

261273
#
262274
# Wait Events - Buffer Pin
@@ -266,6 +278,7 @@ Section: ClassName - WaitEventBufferPin
266278

267279
BUFFER_PIN "Waiting to acquire an exclusive pin on a buffer."
268280

281+
ABI_compatibility:
269282

270283
#
271284
# Wait Events - Extension
@@ -275,6 +288,8 @@ Section: ClassName - WaitEventExtension
275288

276289
Extension "Waiting in an extension."
277290

291+
ABI_compatibility:
292+
278293
#
279294
# Wait Events - LWLock
280295
#
@@ -379,6 +394,7 @@ SubtransSLRU "Waiting to access the sub-transaction SLRU cache."
379394
XactSLRU "Waiting to access the transaction status SLRU cache."
380395
ParallelVacuumDSA "Waiting for parallel vacuum dynamic shared memory allocation."
381396

397+
# No "ABI_compatibility" region here as WaitEventLWLock has its own C code.
382398

383399
#
384400
# Wait Events - Lock
@@ -401,3 +417,5 @@ object "Waiting to acquire a lock on a non-relation database object."
401417
userlock "Waiting to acquire a user lock."
402418
advisory "Waiting to acquire an advisory user lock."
403419
applytransaction "Waiting to acquire a lock on a remote transaction being applied by a logical replication subscriber."
420+
421+
# No "ABI_compatibility" region here as WaitEventLock has its own C code.

0 commit comments

Comments
 (0)