Re: Word-smithing doc changes

On Sat, Jun 25, 2011 at 9:01 PM, Greg Stark <stark(at)mit(dot)edu> wrote:
> I think this commit was ill-advised:
> http://git.postgresql.org/gitweb?p=postgresql.git;a=commitdiff;h=a03feb9354bda5084f19cc952bc52ba7be89f372
>
>     In a concurrent index build, the index is actually entered into the
>     system catalogs in one transaction, then the two table scans occur in a
> -    second and third transaction.
> +    second and third transaction.  All active transactions at the time the
> +    second table scan starts, not just ones that already involve the table,
> +    have the potential to block the concurrent index creation until they
> +    finish.  When checking for transactions that could still use the original
> +    index, concurrent index creation advances through potentially interfering
> +    older transactions one at a time, obtaining shared locks on their virtual
> +    transaction identifiers to wait for them to complete.
>
>
> Seems way to implementation-specific and detailed for a user to make
> heads or tails of. Except in the sections talking about locking
> internals we don't talk about "shared locks on virtual transactions
> identifiers" we just talk about waiting for a transaction to complete.
> And looping over the transactions one by one is purely an
> implementation detail and uninteresting to users. Also it uses
> ill-defined terms like "active transactions", "potentially interfering
> older transactions", and  "original index" -- from the user's point of
> view there's only one index and it just isn't completely built yet.
>
> Are we not yet in string-freeze though? I'll go ahead and edit it if
> people don't mind. I'm curious to see the original complaint though.

We don't have a string freeze, and certainly not for the
documentation, so if you'd like to wordsmith some more, have at it.
But it would probably be best to post your revised version and solicit
feedback before committing, since there was quite a bit of discussion
about that change before it was made. (Sorry, don't have the pointer
at the moment...)

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company