Re: pg_get_multixact_members not documented

Thanks for the review!

> +1. PFA diff of some edits. Please incorporate them in
> your patch if you find them correct.

sure, the diff looks fine to me. will fix.

> We developers may understand the mode text "sh", "keysh" etc. But it may not be user friendly.

yes, I can see that being a point of confusion.

> It would have been better if the function would have reported standard modes as described in [1]
> but we can't change that now.

Really, the section this relates to is row-level locks [0], and for
multixact, there are 2 additional
modes "nokeyupd" which refer to locks takes by updated in no key mode,
and "upd" which
are other types of updates and deletes.

> It might help if we add mapping in the documentation.

I am not too thrilled with a new table mapping, because of the maintenance
aspect of keeping it up-to-date ( not that locks change often or ever
). I rather
describe that the modes are abbreviated names for locks referenced in
[1] and that
there are also some additional modes specific to multixact.

> "" ... each member of the multixact identified by the given mxid' sounds more
> accurate compared to " ... each member of a given multixact ID". That document
> page seems to differentiate between a transaction and transaction ID. I think we
> should try to do the same for multixact.

I like my wording more. It fits the style of the way we describe
functions better. Also,
we don't use "mxid" in the docs, but do use "Transaction ID" and "multixact ID"

I did change " for each " to "of each", which is more accurate.

>> However, this function does not appear to be very practical to use, because
>> the only visible MXID to the user is the oldest one, via pg_database.datminmxid
>> or pg_class.relfrozenxid, or with the help of the contrib extension pgrowlocks.
>
>
> If somebody starts from a row itself e.g. select xmax, * from t1 ... ,
> this function gives the transactions that have locked a given row. So not that useless.

I did not mean "useless", but I did say "not practical", as it
requires a bit of understanding
of the multixact system and multixact ID generation to use. The
example usage you mention
and the example I mentioned earlier [1] demonstrates this.

[0] https://www.postgresql.org/docs/current/explicit-locking.html#LOCKING-ROWS
[1] https://www.postgresql.org/message-id/CAA5RZ0vJat3-VumsTGagxzY35T%3DrCSNyH9GXwkdB3-FFY4as8A%40mail.gmail.com

See v3 addressing the comments.

--
Sami