Re: Word-smithing doc changes

On Wed, Nov 30, 2011 at 09:47:40PM -0800, Greg Smith wrote:
> On 11/30/2011 10:20 AM, Greg Stark wrote:
> >Given your confusion it's clear that we have to explain that it will
> >wait one by one for each transaction that was started before the index
> >was created to finish.
>
> When the index was created is a fuzzy thing though. It looked to me
> like it makes this check at the start of Phase 2. If I read "when
> the index was created" in the manual, I would assume that meant "the
> instant at which CREATE INDEX CONCURRENTLY started". I don't think
> that's actually the case though; it's actually delayed to the
> beginning of Phase 2 start, which can easily be hours later for big
> indexes. Please correct me if I'm reading that wrong.
>
> > I don't think we need to explain how that's
> >implemented. If we do it should be set aside in some way, something
> >like "(see virtual transaction id locks in<href...>)".
>
> Fair enough. There is this wording in the pg_locks documentation:
> "When one transaction finds it necessary to wait specifically for
> another transaction, it does so by attempting to acquire share lock
> on the other transaction ID (either virtual or permanent ID
> depending on the situation). That will succeed only when the other
> transaction terminates and releases its locks."
>
> Linking to that instead of trying to duplicate it is a good idea.
> Another good, related idea might be to expand the main "Concurrency
> Control" chapter to include this information. When I re-read
> "Explicit Locking" again:
> http://developer.postgresql.org/pgdocs/postgres/explicit-locking.html
> it strikes me it would be nice to add "Transaction Locks" as an full
> entry there. The trivia around how those work is really kind of
> buried in the pg_locks section.
>
> >I just want to keep in mind that the reader here is trying to
> >understand how to use create index concurrently, not understand how
> >Postgres's locking infrastructure works in general.
>
> To the extent they can be ignorant of the locking infrastructure,
> that's true. This operation is complicated enough that I don't
> think we can hide too many of the details from the users, while
> still letting them assess the risk and potential duration
> accurately.

The concurrent index documentation under discussion above was never
updated, so I took a stab at it, attached.

Greg, I looked at adding a mention of the virtual transaction wait to
the "explicit-locking" section as you suggested, and found those were
all user-visible locking, while this is internal locking. I did find a
clear description of transaction id locking in the pg_locks system view
docs, so I just referenced that.

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ It's impossible for everything to be true. +