Misleading description for IPC wait events in PostgreSQL documentation

From: SAMEER KUMAR <sameer(dot)kasi200x(at)gmail(dot)com>
To: pgsql-docs(at)postgresql(dot)org
Subject: Misleading description for IPC wait events in PostgreSQL documentation
Date: 2023-03-13 16:09:36
Message-ID: CAGPeHmjeoXCc+prH0EUewmCRipiRr1tAtKwvPApJ8SHEAuFc+A@mail.gmail.com
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-docs

Hi,

While preparing for my presentation on PostgreSQL Wait Events at PgConf
India, I was trying to understand *IPC:XactGroupUpdate* in more detail.
PostgreSQL documentation [1] mentions:

> A process is waiting for the group leader to update the transaction
status at the end of a _parallel operation_.

I was looking at `TransactionGroupUpdateXidStatus` in PostgreSQL code
(`clog.c`)
Line `481` [2] sets this wait event.

And after reading the code - my understanding is it does not necessarily
need to be a "_parallel operation_". Or maybe I am just misinterpreting
"parallel operation" in this context. But it is possible for other users to
confuse it with the parallel query feature.

**My understanding is**
In order to avoid `XactSLRULock` being passed between backends, backends
waiting for it will add themselves to the queue [3]. The first backend in
the queue (also the leader) will be the only one to
acquire `XactSLRULock` and update the XID status for all those pids which
are in the queue. This wait event `IPC:XactGroupUpdate` is observed in
other backened processes in queue who are waiting for the group leader to
update the XID status.

I recommend making a change to PostgreSQL docs to clearly indicate what
this wait event means:

> When concurrent processes are trying to update transaction status in the
same page of commit logs, a group leader is assigned to perform the update
and other processes wanting to perform the update wait on this IPC wait
event.

OR

> When multiple backend processes wait on a group leader to update their
transaction status, so that PostgreSQL can avoid passing around the
LwLock `XactSLRULock` between multiple backend processes.

A similar change should be done for `ProcArrayGroupUpdate` to indicate that
the wait event is a result of concurrent backend processes trying to clear
the transaction id (instead of saying "parallel operation").

Thoughts?

[1]
https://www.postgresql.org/docs/current/monitoring-stats.html#WAIT-EVENT-IPC-TABLE

[2]
https://github.com/postgres/postgres/blob/master/src/backend/access/transam/clog.c#L481

[3]
https://github.com/postgres/postgres/blob/master/src/backend/access/transam/clog.c#L399

Thanks,
Sameer
DB Specialist,
Amazon Web Services

Browse pgsql-docs by date

  From Date Subject
Next Message Daniel Gustafsson 2023-03-14 11:22:40 The use "Postgres" in docs
Previous Message Tomas Pospisek 2023-03-13 09:00:36 Re: Make SSPI documentation clearer