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
