Horton

Re: Autogenerate some wait events code and documentation

Alvaro Herrera <alvherre@alvh.no-ip.org>

View thread View on postgr.es
From: Alvaro Herrera <alvherre@alvh.no-ip.org>
To: Michael Paquier <michael@paquier.xyz>
Cc: Andres Freund <andres@anarazel.de>, "Drouvot, Bertrand" <bertranddrouvot.pg@gmail.com>, PostgreSQL Hackers <pgsql-hackers@lists.postgresql.org>
Date: 2024-03-18T09:24:00Z
Lists: pgsql-hackers 
On 2023-Aug-28, Michael Paquier wrote:

> I have looked again at that, and switching wait_event_names.txt to use
> two columns made of the typedef definitions and the docs like is not a
> problem:
> FOO_BAR   "Waiting on Foo Bar."
> 
> WAIT_EVENT_ is appended to the typedef definitions in the script.  The
> wait event names like "FooBar" are generated from the enums by
> splitting using their underscores and doing some lc().  Lock and
> LWLock don't need to change.  This way, it is easy to grep the wait
> events from the source code and match them with wait_event_names.txt.

FTR I had a rather unpleasant time last week upon finding a wait event
named PgSleep.  If you grep for that, there are no matches at all; and I
spent ten minutes (for real) trying to figure out where that was coming
from, until I remembered this thread.

Now you have to guess that not only random lowercasing is happening, but
also underscore removal.  This is not a good developer experience and I
think we should rethink this choice.  It would be infinitely more
usable, and not one bit more difficult, to make these lines be

WAIT_EVENT_FOO_BAR	FooBar	"Waiting on Foo Bar."

then there is no guessing involved.

-- 
Álvaro Herrera               48°01'N 7°57'E  —  https://www.EnterpriseDB.com/
"The important things in the world are problems with society that we don't
understand at all. The machines will become more complicated but they won't
be more complicated than the societies that run them."    (Freeman Dyson)

Commits

  1. Add "ABI_compatibility" regions to wait_event_names.txt

  2. Remove column for wait event names in wait_event_names.txt

  3. Use more consistent names for wait event objects and types

  4. Add information about line contents on parsing failure of wait_event_names.txt

  5. Remove double quotes from the second column of wait_event_names.txt

  6. Generate automatically code and documentation related to wait events

  7. Refactor some code related to wait events "BufferPin" and "Extension"

  8. doc: Fix ordering of entries in wait event table for I/O type