Re: New docs chapter on Transaction Management and related changes

+1 for this new chapter. This latest patch looks pretty good. I think
that introducing the concept of "sub-commit" as in Simon's follow-up
patch clarifies things, though the word itself looks very odd. Maybe
it's okay. The addition of the savepoint example looks good also.

On 2022-Oct-13, Bruce Momjian wrote:

> + <para>
> + <productname>PostgreSQL</productname> supports a two-phase commit (2PC)
> + protocol that allows multiple distributed systems to work together
> + in a transactional manner. The commands are <command>PREPARE
> + TRANSACTION</command>, <command>COMMIT PREPARED</command> and

I suggest/request that we try to avoid breaking tagged constants in
DocBook; doing so makes it much easier to miss them later when grepping
for them (don't laugh, it has happened to me). Also, it breaks
formatting in some weird cases. I know this makes editing a bit harder
because you can't just reflow with your editor like you would normal
text. So this'd be:

+ in a transactional manner. The commands are <command>PREPARE TRANSACTION</command>,
+ <command>COMMIT PREPARED</command> and

with whatever word wrapping you like, except breaking between PREPARE
and TRANSACTION.

> + <para>
> + In addition to <literal>vxid</literal> and <type>xid</type>,
> + when a transaction is prepared it is also identified by a Global
> + Transaction Identifier (<acronym>GID</acronym>). GIDs
> + are string literals up to 200 bytes long, which must be
> + unique amongst other currently prepared transactions.
> + The mapping of GID to xid is shown in <link
> + linkend="view-pg-prepared-xacts"><structname>pg_prepared_xacts</structname></link>.
> + </para>

Maybe say "is prepared for two-phase commit", to make the topic of this
paragraph more obvious?

> + <para>
> + Lock waits on table-level locks are shown waiting for
> + <structfield>virtualxid</structfield>, while lock waits on row-level
> + locks are shown waiting for <structfield>transactionid</structfield>.
> + Row-level read and write locks are recorded directly in locked
> + rows and can be inspected using the <xref linkend="pgrowlocks"/>
> + extension. Row-level read locks might also require the assignment
> + of multixact IDs (<literal>mxid</literal>). Mxids are recorded in
> + the <filename>pg_multixact</filename> directory.
> + </para>

Hmm, ok.

> + <para>
> + The parent xid of each subxid is recorded in the
> + <filename>pg_subtrans</filename> directory. No entry is made for
> + top-level xids since they do not have a parent, nor is an entry made
> + for read-only subtransactions.
> + </para>

Maybe say "the immediate parent xid of each ...", or is it too obvious?

--
Álvaro Herrera Breisgau, Deutschland — https://www.EnterpriseDB.com/
"Las cosas son buenas o malas segun las hace nuestra opinión" (Lisias)