few more wait events to add to docs

On 2019-Mar-05, Jeremy Schneider wrote:

It's possible I'm misreading this, but I'm thinking that commits
cc5f8136 and ab9e0e71 added a few tranches which we need to add to the docs.

session_dsa, session_record_table, session_typmod_table, and
shared_tuplestore

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

/messages/by-id/CAB7nPqSU1=-3fQVZ+ncgm5VmRO4LSzjgQSmoYgwiZs2HvpyKBA@mail.gmail.com
:-)

--
�lvaro Herrera https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

On Wed, Mar 6, 2019 at 2:18 PM Alvaro Herrera <alvherre@2ndquadrant.com> wrote:

On 2019-Mar-05, Jeremy Schneider wrote:

It's possible I'm misreading this, but I'm thinking that commits
cc5f8136 and ab9e0e71 added a few tranches which we need to add to the docs.

session_dsa, session_record_table, session_typmod_table, and
shared_tuplestore

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

/messages/by-id/CAB7nPqSU1=-3fQVZ+ncgm5VmRO4LSzjgQSmoYgwiZs2HvpyKBA@mail.gmail.com

Here's some missing documentation.

Hmm, yeah. I wish these were alphabetised, I wish there was an
automated warning about this, I wish these tranches were declared a
better way that by adding code in RegisterLWLockTranches().

--
Thomas Munro
https://enterprisedb.com

On Wed, Mar 06, 2019 at 02:21:15PM +1300, Thomas Munro wrote:

Here's some missing documentation.

The addition looks fine to me.

Hmm, yeah. I wish these were alphabetised, I wish there was an
automated warning about this, I wish these tranches were declared a
better way that by adding code in RegisterLWLockTranches().

Why not using this occasion to reorganize the LWLock and Lock sections
so as their entries are fully alphabetized then? I have made an
effort in this direction in 5ef037c for all the sections except these
two. And honestly getting all these organized would really help
documentation readers.
--
Michael

On 3/5/19 18:49, Michael Paquier wrote:

Why not using this occasion to reorganize the LWLock and Lock sections
so as their entries are fully alphabetized then? I have made an
effort in this direction in 5ef037c for all the sections except these
two. And honestly getting all these organized would really help
documentation readers.

Right now, the LWLock documentation implicitly follows a predictable
pattern, so it's not really that hard to check for completeness.  I'm
not sure to what extent you want to alphabetize, but I think the current
structure isn't bad:

LWLock order in documentation:
1) CamelCase LWLocks: individually named - see lwlocknames.txt
2) lowercase LWLocks: tranches
2a) SLRUs - see SimpleLruInit() callers on doxygen
2b) Shared Buffer (buffer_content, buffer_io)
2c) Individually Named - see RegisterLWLockTranches() in lwlock.c

[see attached screenshot image... spoiler alert, it'll be a slide in my
talk at PgConf NY]

If anything, I think we might just want to add comments to
RegisterLWLockTranches() and lwlocknames.txt with links to the doc file
that needs to be updated whenever a new tranche is added.

Not sure the best place for a comment on SLRUs (is SimpleLruInit a good
place?)... but I'm kindof hopeful that we're not adding many more new
SLRUs anyway and that people would bias toward leveraging the buffer
cache when possible.

I'd rather make this pattern explicit in the docs than lose it... it
greatly helps me understand what some particular wait event is, and
where I need to look in the code to find it.

-Jeremy

--
Jeremy Schneider
Database Engineer
Amazon Web Services

On Wed, Mar 06, 2019 at 11:08:12AM -0800, Jeremy Schneider wrote:

LWLock order in documentation:
1) CamelCase LWLocks: individually named - see lwlocknames.txt
2) lowercase LWLocks: tranches
2a) SLRUs - see SimpleLruInit() callers on doxygen
2b) Shared Buffer (buffer_content, buffer_io)
2c) Individually Named - see RegisterLWLockTranches() in lwlock.c

Hm, OK. Perhaps I lack some user insight on the matter. Thanks for
the feedback! Still there are some areas where we could make the
micro-ordering better. For example replication_slot_io and buffer_io
are I/O specific still they get in the middle of the page, still we
want buffer_content close by.

One thing that I think we could do is reorganize at least
alphabetically the section for "Lock". Each item does not really rely
on others. What do you think?

If anything, I think we might just want to add comments to
RegisterLWLockTranches() and lwlocknames.txt with links to the doc file
that needs to be updated whenever a new tranche is added.

Yes, that would surely help.

Not sure the best place for a comment on SLRUs (is SimpleLruInit a good
place?)... but I'm kindof hopeful that we're not adding many more new
SLRUs anyway and that people would bias toward leveraging the buffer
cache when possible.

A reference at the top of SimpleLruInit() sounds good to me.
--
Michael

On Thu, Mar 07, 2019 at 11:25:10AM +0900, Michael Paquier wrote:

On Wed, Mar 06, 2019 at 11:08:12AM -0800, Jeremy Schneider wrote:

If anything, I think we might just want to add comments to
RegisterLWLockTranches() and lwlocknames.txt with links to the doc file
that needs to be updated whenever a new tranche is added.

Yes, that would surely help.

Not sure the best place for a comment on SLRUs (is SimpleLruInit a good
place?)... but I'm kindof hopeful that we're not adding many more new
SLRUs anyway and that people would bias toward leveraging the buffer
cache when possible.

A reference at the top of SimpleLruInit() sounds good to me.

Thinking more about that, a comment at the top of SimpleLruInit() and
RegisterLWLockTranches() are both good things.

So please find attached a patch which does the following things to
address this thread:
- Reorder the list of events in the Lock section in alphabetical order
(not LWLock!).
- Add the missing event entries, which is what Thomas has provided.
- Add more documentation to mention the doc updates.

Thoughts?
--
Michael