Re: New docs chapter on Transaction Management and related changes - Mailing list pgsql-hackers

On Fri, 14 Oct 2022 at 09:46, Alvaro Herrera <alvherre@alvh.no-ip.org> wrote:
>
> +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?

+1 to all of those suggestions

-- 
Simon Riggs                http://www.EnterpriseDB.com/