Generate wait event list and docs from text file

From: Michael Paquier <michael(dot)paquier(at)gmail(dot)com>
To: PostgreSQL mailing lists <pgsql-hackers(at)postgresql(dot)org>
Subject: Generate wait event list and docs from text file
Date: 2017-08-15 06:58:57
Message-ID: CAB7nPqSU1=-3fQVZ+ncgm5VmRO4LSzjgQSmoYgwiZs2HvpyKBA@mail.gmail.com
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-hackers

Hi all,

As $subject has been touched on two threads recently
(https://www.postgresql.org/message-id/CAB7nPqTbHLcHFn6m11tfpwAdgz8BmnBza2jjN9AK=SdX_kBJZQ@mail.gmail.com
and https://www.postgresql.org/message-id/20170808213537.wkmmagf2a6i3hjyi@alvherre.pgsql)
the list of wait event and their category are becoming harder to
maintain because of their number and the fact that:
1) It is easy to add a wait event and...
2) It is easy to not update its documentation.
3) the documentation tables get easily broken.

As I have participated in the situation present now, I propose to
write a patch to make the maintenance of the whole thing easier,
because wait events are important, and because I see more of them
added in the future. So here is a thread dedicated to this problem, so
let's discuss a solution to make things more maintainable.

So, like errcodes.txt, let's use two small perl scripts that generate
the set of SGML summarizing wait events and an include file with all
the wait events listed (enum list and sections).

One wait event is associated with the following set of data:
- A class, like Activity, IPC, BufferPin, LWLock, etc.
- A user-visible event name, like AutoVacuumMain, etc.
- A enum-like name, like WAIT_EVENT_AUTOVACUUM_MAIN.
- A description, like "Waiting in main loop of autovacuum launcher process."
Note as well that a class has a user-visible name, and a symbol name.

Using this set of meta-data, it is possible to generate the SGML
tables and the set of include tables.

While thinking about that, I have been wondering about what could be
the shape of the text file holding this meta-data, which needs to be
readable. So here is an idea:
# Comment, which gets ignored when processing.
# First set a section, followed by all the events in it
# A section is name with a class name, and an object name. Perhaps the
object name could be dynamically generated?
Section: ClassName PG_CLASS_NAME

# Each event is listed: user-visible event name, object name,
description within quotes
EventName WAIT_EVENT_NAME "Description of this event name"
EventName2 WAIT_EVENT_NAME_2 "Description of this event name 2"

There is a link between the class name and its variable name, as well
as between the event name and its variable name, so both could be
generated dynamically:
- the class name is upper-cased, and prefixed with PG_.
- the event name is upper-cased, and prefixed with WAIT_EVENT.

Maintaining the description of the object within quotes makes parsing
with a regex easier.

So, thoughts?
--
Michael

Responses

Browse pgsql-hackers by date

  From Date Subject
Next Message Fabien COELHO 2017-08-15 06:59:40 Re: pgbench more operators & functions
Previous Message Andres Freund 2017-08-15 06:53:48 Re: Pluggable storage