Re: Word-smithing doc changes

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.

--
Greg Smith 2ndQuadrant US greg(at)2ndQuadrant(dot)com Baltimore, MD
PostgreSQL Training, Services, and 24x7 Support www.2ndQuadrant.us