On Fri, Jun 6, 2025 at 4:15 AM Sami Imseih <samims...@gmail.com> wrote:
> > 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. > + .... The lock modes are abbreviated names for the types of row-level + locks described in <xref linkend="locking-rows"/>. It's not clear, without some effort, which lock mode go with which row lock in that description. For example, "keysh" does not have "for" in it but "fornokeyupd" does. How about rephrasing this as "The lock modes "keysh", "sh", fornokeyupd", and "forupd" correspond to <literal>FOR KEY SHARE</literal>, <literal>FOR SHARE</literal>, <literal>FOR NO KEY UPDATE</literal>, and <literal>FOR UPDATE</literal> row level locks respectively as described in <xref linkend="locking-rows"/>." It will still need an update if the row lock modes are changed in the future, but that risk goes with the two multixact specific modes as well. And the risk is minimal. Do we want to add the section "Multixact Information Functions" after other transaction related sections like "Transaction ID and Snapshot Information Function" and " Committed Transaction Information Functions" instead of adding it at the end? -- Best Wishes, Ashutosh Bapat
