Re: Need help understanding pg_locks

Can someone help me understand pg_locks? There are three fields related
to virtual and real xids:

virtualtransaction | text |
transactionid | xid |
virtualxid | text |

Our docs say 'virtualtransaction' is:

Virtual ID of the transaction that is holding or awaiting this lock

This field was clear to me.

and 'transactionid' is documented as:

ID of a transaction, or null if the object is not a transaction ID

In my testing it was the (non-virtual) xid of the lock holder. Is that
correct? Can it be a waiter?

'virtualxid' is documented as:

Virtual ID of a transaction, or null if the object is not a
virtual transaction ID

In my testing this field is for locking your own vxid, meaning it owned
by its own vxid.

I looked at the C code in /pg/backend/utils/adt/lockfuncs.c and was
confused.

Clearly our documentation is lacking in this area and I would like to
clarify it.

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

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

On Jul10, 2011, at 06:01 , Bruce Momjian wrote:
> Can someone help me understand pg_locks? There are three fields related
> to virtual and real xids:
>
> virtualtransaction | text |
> transactionid | xid |
> virtualxid | text |
>
> Our docs say 'virtualtransaction' is:
>
> Virtual ID of the transaction that is holding or awaiting this lock
>
> This field was clear to me.
>
> and 'transactionid' is documented as:
>
> ID of a transaction, or null if the object is not a transaction ID
>
> In my testing it was the (non-virtual) xid of the lock holder. Is that
> correct? Can it be a waiter?

'transactionid' is locked (or waited for) xid, just as 'relation' is
the oid of a locked or waited for pg_class entry.

What you saw was probably the lock each transaction hold on its own xid
(if it has one, that is). There can be waiters on locks of type
'transactionid' - e.g. a transaction which tries to update a tuple
modified by transaction Y will wait on Y's xid until Y commits or rolls
back, and then take appropriate action.

> 'virtualxid' is documented as:
>
> Virtual ID of a transaction, or null if the object is not a
> virtual transaction ID
>
> In my testing this field is for locking your own vxid, meaning it owned
> by its own vxid.

Its the virtual-xid version of 'transactionid', i.e. the virtual xid
which is locked or being waited for.

Again, each transaction hold a lock on its own vxid, so that is was
you saw. Waiters on 'virtualxid' are much less common, but for example
CREATE INDEX CONCURRENTLY does that.

> Clearly our documentation is lacking in this area and I would like to
> clarify it.

It seems that we should put a stronger emphasis on which fields of
pg_locks refer to the locked (or waited for) object, and which to the
lock holder (or waiter).

AFAICS, currently all fields up to (but excluding) 'virtualtransaction'
describe the locked objects. Depending on 'locktype', some fields are
always NULL (like 'relation' for locktype 'virtualxid').

All later fields (virtualtransaction, pid, mode, granted) describe the
lock holder or waiter.

best regards,
Florian Pflug

Florian Pflug wrote:
> On Jul10, 2011, at 06:01 , Bruce Momjian wrote:
> > Can someone help me understand pg_locks? There are three fields related
> > to virtual and real xids:
> >
> > virtualtransaction | text |
> > transactionid | xid |
> > virtualxid | text |
> >
> > Our docs say 'virtualtransaction' is:
> >
> > Virtual ID of the transaction that is holding or awaiting this lock
> >
> > This field was clear to me.
> >
> > and 'transactionid' is documented as:
> >
> > ID of a transaction, or null if the object is not a transaction ID
> >
> > In my testing it was the (non-virtual) xid of the lock holder. Is that
> > correct? Can it be a waiter?
>
> 'transactionid' is locked (or waited for) xid, just as 'relation' is
> the oid of a locked or waited for pg_class entry.
>
> What you saw was probably the lock each transaction hold on its own xid
> (if it has one, that is). There can be waiters on locks of type
> 'transactionid' - e.g. a transaction which tries to update a tuple
> modified by transaction Y will wait on Y's xid until Y commits or rolls
> back, and then take appropriate action.
>
> > 'virtualxid' is documented as:
> >
> > Virtual ID of a transaction, or null if the object is not a
> > virtual transaction ID
> >
> > In my testing this field is for locking your own vxid, meaning it owned
> > by its own vxid.
>
> Its the virtual-xid version of 'transactionid', i.e. the virtual xid
> which is locked or being waited for.
>
> Again, each transaction hold a lock on its own vxid, so that is was
> you saw. Waiters on 'virtualxid' are much less common, but for example
> CREATE INDEX CONCURRENTLY does that.
>
> > Clearly our documentation is lacking in this area and I would like to
> > clarify it.
>
> It seems that we should put a stronger emphasis on which fields of
> pg_locks refer to the locked (or waited for) object, and which to the
> lock holder (or waiter).
>
> AFAICS, currently all fields up to (but excluding) 'virtualtransaction'
> describe the locked objects. Depending on 'locktype', some fields are
> always NULL (like 'relation' for locktype 'virtualxid').
>
> All later fields (virtualtransaction, pid, mode, granted) describe the
> lock holder or waiter.

Thank you. I think my confusion is that virtualtransaction is the lock
holder/waiter, and the other two are actual locks. The attached doc
patch clarifies that. I had actually realized this a few weeks ago and
forgot, meaning this is pretty confusing.

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

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

On Jul11, 2011, at 05:47 , Bruce Momjian wrote:
> Thank you. I think my confusion is that virtualtransaction is the lock
> holder/waiter, and the other two are actual locks. The attached doc
> patch clarifies that. I had actually realized this a few weeks ago and
> forgot, meaning this is pretty confusing.

For consistency, I guess it should say "lock object" instead of simply
"object" the description of all the columns up to (and including)
"objsubid", not only those of "virtualxid" and "transactionid".

I'd also slightly prefer "locked object" over "lock object", because
the lock itself probably isn't a standalone entity in the mind of
most users. And for people familiar with our locking infrastructure,
the actually correct term would be "lock tag" I believe.

In any case, +1 for improving the description there.

best regards,
Florian Pflug

Florian Pflug <fgp(at)phlo(dot)org> writes:
> On Jul11, 2011, at 05:47 , Bruce Momjian wrote:
>> Thank you. I think my confusion is that virtualtransaction is the lock
>> holder/waiter, and the other two are actual locks. The attached doc
>> patch clarifies that. I had actually realized this a few weeks ago and
>> forgot, meaning this is pretty confusing.

> For consistency, I guess it should say "lock object" instead of simply
> "object" the description of all the columns up to (and including)
> "objsubid", not only those of "virtualxid" and "transactionid".

Yeah, I think this patch is going in the wrong direction altogether.
It would be better to modify the description of virtualtransaction
and pid to say that those are the "locking" entity.

regards, tom lane

On Jul11, 2011, at 17:11 , Tom Lane wrote:
> Florian Pflug <fgp(at)phlo(dot)org> writes:
>> On Jul11, 2011, at 05:47 , Bruce Momjian wrote:
>>> Thank you. I think my confusion is that virtualtransaction is the lock
>>> holder/waiter, and the other two are actual locks. The attached doc
>>> patch clarifies that. I had actually realized this a few weeks ago and
>>> forgot, meaning this is pretty confusing.
>
>> For consistency, I guess it should say "lock object" instead of simply
>> "object" the description of all the columns up to (and including)
>> "objsubid", not only those of "virtualxid" and "transactionid".
>
> Yeah, I think this patch is going in the wrong direction altogether.
> It would be better to modify the description of virtualtransaction
> and pid to say that those are the "locking" entity.

Hm, we already kinda of say that. Both descriptions include the phrase
"... holding or awaiting this lock.". The column "mode" says
"... held or desired by this process", which I guess is similar enough
to make it clear that these are related.

Its the columns which refer to the locked object which simply say
"object", and thus leave it open if that means locked or a locking.

Could we split that table in two parts, one for the fields referring
to the locked object and one for the locking entity, or does that depart
too far from the way we document other system catalogs and views?

If splitting it into two parts is too radical, how about adding a column
"Refers To" which says either "Locked Object" or "Locking Entity"?

best regards,
Florian Pflug

Florian Pflug <fgp(at)phlo(dot)org> writes:
> On Jul11, 2011, at 17:11 , Tom Lane wrote:
>> Yeah, I think this patch is going in the wrong direction altogether.
>> It would be better to modify the description of virtualtransaction
>> and pid to say that those are the "locking" entity.

> Hm, we already kinda of say that. Both descriptions include the phrase
> "... holding or awaiting this lock.". The column "mode" says
> "... held or desired by this process", which I guess is similar enough
> to make it clear that these are related.

> Its the columns which refer to the locked object which simply say
> "object", and thus leave it open if that means locked or a locking.

> Could we split that table in two parts, one for the fields referring
> to the locked object and one for the locking entity, or does that depart
> too far from the way we document other system catalogs and views?

Then you'd have to join them, which would not be an improvement from
anybody's standpoint.

Maybe we could just add a paragraph above the "pg_locks Columns" table
that says explicitly that virtualtransaction and pid describe the entity
holding or awaiting the lock, and the others describe the object being
locked? Any way you slice it, putting this information into the
per-column table is going to be repetitive.

regards, tom lane

Tom Lane wrote:
> Florian Pflug <fgp(at)phlo(dot)org> writes:
> > On Jul11, 2011, at 05:47 , Bruce Momjian wrote:
> >> Thank you. I think my confusion is that virtualtransaction is the lock
> >> holder/waiter, and the other two are actual locks. The attached doc
> >> patch clarifies that. I had actually realized this a few weeks ago and
> >> forgot, meaning this is pretty confusing.
>
> > For consistency, I guess it should say "lock object" instead of simply
> > "object" the description of all the columns up to (and including)
> > "objsubid", not only those of "virtualxid" and "transactionid".
>
> Yeah, I think this patch is going in the wrong direction altogether.
> It would be better to modify the description of virtualtransaction
> and pid to say that those are the "locking" entity.

OK, so as I understand it, in pg_locks:

Column | Type | Modifiers
--------------------+----------+-----------
locktype | text |
database | oid |
relation | oid |
page | integer |
tuple | smallint |
virtualxid | text |
transactionid | xid |
classid | oid |
objid | oid |
objsubid | smallint |

virtualtransaction | text |
pid | integer |
mode | text |
granted | boolean |

It is the last four that are related to the "locking entity". I don't
see a way of improving the description of the last four columns:

http://developer.postgresql.org/pgdocs/postgres/view-pg-locks.html

What was unclear to me was that the earlier columns (illogically)
vaguely represented the locked object.

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

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

Tom Lane wrote:
> Florian Pflug <fgp(at)phlo(dot)org> writes:
> > On Jul11, 2011, at 17:11 , Tom Lane wrote:
> >> Yeah, I think this patch is going in the wrong direction altogether.
> >> It would be better to modify the description of virtualtransaction
> >> and pid to say that those are the "locking" entity.
>
> > Hm, we already kinda of say that. Both descriptions include the phrase
> > "... holding or awaiting this lock.". The column "mode" says
> > "... held or desired by this process", which I guess is similar enough
> > to make it clear that these are related.
>
> > Its the columns which refer to the locked object which simply say
> > "object", and thus leave it open if that means locked or a locking.
>
> > Could we split that table in two parts, one for the fields referring
> > to the locked object and one for the locking entity, or does that depart
> > too far from the way we document other system catalogs and views?
>
> Then you'd have to join them, which would not be an improvement from
> anybody's standpoint.
>
> Maybe we could just add a paragraph above the "pg_locks Columns" table
> that says explicitly that virtualtransaction and pid describe the entity
> holding or awaiting the lock, and the others describe the object being
> locked? Any way you slice it, putting this information into the
> per-column table is going to be repetitive.

Frankly, whenever anyone says "object", they might as well call it
"thing". It seems to be a content-less word. Maybe just replace the
word "object" with "lock".

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

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

Bruce Momjian <bruce(at)momjian(dot)us> writes:
> Tom Lane wrote:
>> Maybe we could just add a paragraph above the "pg_locks Columns" table
>> that says explicitly that virtualtransaction and pid describe the entity
>> holding or awaiting the lock, and the others describe the object being
>> locked? Any way you slice it, putting this information into the
>> per-column table is going to be repetitive.

> Frankly, whenever anyone says "object", they might as well call it
> "thing". It seems to be a content-less word. Maybe just replace the
> word "object" with "lock".

No, because that conflates the lock with the thing being locked.
Fuzzing that semantic difference isn't going to make it less confusing.

regards, tom lane

On Jul11, 2011, at 17:31 , Bruce Momjian wrote:
> Tom Lane wrote:
>> Florian Pflug <fgp(at)phlo(dot)org> writes:
>>> On Jul11, 2011, at 17:11 , Tom Lane wrote:
>>>> Yeah, I think this patch is going in the wrong direction altogether.
>>>> It would be better to modify the description of virtualtransaction
>>>> and pid to say that those are the "locking" entity.
>>
>>> Hm, we already kinda of say that. Both descriptions include the phrase
>>> "... holding or awaiting this lock.". The column "mode" says
>>> "... held or desired by this process", which I guess is similar enough
>>> to make it clear that these are related.
>>
>>> Its the columns which refer to the locked object which simply say
>>> "object", and thus leave it open if that means locked or a locking.
>>
>>> Could we split that table in two parts, one for the fields referring
>>> to the locked object and one for the locking entity, or does that depart
>>> too far from the way we document other system catalogs and views?
>>
>> Then you'd have to join them, which would not be an improvement from
>> anybody's standpoint.
>>
>> Maybe we could just add a paragraph above the "pg_locks Columns" table
>> that says explicitly that virtualtransaction and pid describe the entity
>> holding or awaiting the lock, and the others describe the object being
>> locked? Any way you slice it, putting this information into the
>> per-column table is going to be repetitive.
>
> Frankly, whenever anyone says "object", they might as well call it
> "thing". It seems to be a content-less word. Maybe just replace the
> word "object" with "lock".

I like that, as long as we make it ".. lock is/isn't *on* a ...", and not
just "... lock is/isn't a". After all, the lock very clearly isn't a
relation or xid or whatever - it's a, well, lock.

We'd then have
OID of the database in which the lock exists, or zero if the lock is on a
shared object, or null if the lock is on a transaction ID.

OID of the relation, or null if the lock is not on a relation or part of a
relation.

...

ID of a transaction, or null if the lock is not on a transaction ID

...

best regards,
Florian Pflug

Bruce Momjian <bruce(at)momjian(dot)us> wrote:

> OK, so as I understand it, in pg_locks:
>
> Column | Type | Modifiers
> --------------------+----------+-----------
> locktype | text |
> database | oid |
> relation | oid |
> page | integer |
> tuple | smallint |
> virtualxid | text |
> transactionid | xid |
> classid | oid |
> objid | oid |
> objsubid | smallint |
>
> virtualtransaction | text |
> pid | integer |
> mode | text |
> granted | boolean |
>
> It is the last four that are related to the "locking entity".

> vaguely represented the locked object.

I think more accurately:

Information about the lock requester:

virtualtransaction, pid

Information about what is being locked:

database, relation, page, tuple, virtualxid, transactionid, classid,
objid, objsubid (where NULL means "not applicable to this lock)

Information about the lock itself:

locktype, mode, granted

-Kevin

Florian Pflug wrote:
> On Jul11, 2011, at 17:31 , Bruce Momjian wrote:
> > Tom Lane wrote:
> >> Florian Pflug <fgp(at)phlo(dot)org> writes:
> >>> On Jul11, 2011, at 17:11 , Tom Lane wrote:
> >>>> Yeah, I think this patch is going in the wrong direction altogether.
> >>>> It would be better to modify the description of virtualtransaction
> >>>> and pid to say that those are the "locking" entity.
> >>
> >>> Hm, we already kinda of say that. Both descriptions include the phrase
> >>> "... holding or awaiting this lock.". The column "mode" says
> >>> "... held or desired by this process", which I guess is similar enough
> >>> to make it clear that these are related.
> >>
> >>> Its the columns which refer to the locked object which simply say
> >>> "object", and thus leave it open if that means locked or a locking.
> >>
> >>> Could we split that table in two parts, one for the fields referring
> >>> to the locked object and one for the locking entity, or does that depart
> >>> too far from the way we document other system catalogs and views?
> >>
> >> Then you'd have to join them, which would not be an improvement from
> >> anybody's standpoint.
> >>
> >> Maybe we could just add a paragraph above the "pg_locks Columns" table
> >> that says explicitly that virtualtransaction and pid describe the entity
> >> holding or awaiting the lock, and the others describe the object being
> >> locked? Any way you slice it, putting this information into the
> >> per-column table is going to be repetitive.
> >
> > Frankly, whenever anyone says "object", they might as well call it
> > "thing". It seems to be a content-less word. Maybe just replace the
> > word "object" with "lock".
>
> I like that, as long as we make it ".. lock is/isn't *on* a ...", and not
> just "... lock is/isn't a". After all, the lock very clearly isn't a
> relation or xid or whatever - it's a, well, lock.
>
> We'd then have
> OID of the database in which the lock exists, or zero if the lock is on a
> shared object, or null if the lock is on a transaction ID.
>
> OID of the relation, or null if the lock is not on a relation or part of a
> relation.
>
> ...
>
> ID of a transaction, or null if the lock is not on a transaction ID

OK, I went with this wording, using "lock object is on" terminology.
Applied patch attached --- adjustments welcomed.

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

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

Bruce Momjian <bruce(at)momjian(dot)us> writes:
> OK, I went with this wording, using "lock object is on" terminology.
> Applied patch attached --- adjustments welcomed.

I think you misunderstood the suggestion. This is not an improvement,
it's just more confusion.

regards, tom lane

Tom Lane wrote:
> Bruce Momjian <bruce(at)momjian(dot)us> writes:
> > OK, I went with this wording, using "lock object is on" terminology.
> > Applied patch attached --- adjustments welcomed.
>
> I think you misunderstood the suggestion. This is not an improvement,
> it's just more confusion.

Well, I thought the "lock on" wording helped avoid the confusion but
obviously I didn't understand more than that. We did have similar
confusion when we clarified the locking C code. For me, "object" was
the stumbler. Do you have any suggested wording? Everyone seems to
agree it needs improvement.

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

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

On Jul13, 2011, at 17:44 , Tom Lane wrote:
> Bruce Momjian <bruce(at)momjian(dot)us> writes:
>> OK, I went with this wording, using "lock object is on" terminology.
>> Applied patch attached --- adjustments welcomed.
>
> I think you misunderstood the suggestion. This is not an improvement,
> it's just more confusion.

FWIW, I agree. First, "lock object" seems redundant - you might just as
well say simply "lock". This is different from "locked object" - there,
the noun "object" servers as a dummy that gives the adjective "locked"
something to refer to.

Also, it now sounds as if we were talking about the storage
location of the lock (as an entity in itself) in some of the sentences.

Here's an example

"Page number within the relation, or null if the lock object
is not on a tuple or relation page".

To me at least, that sounds as if the lock might somehow be stored
on a "relation page".

Maybe "on" is still too generic. What if we said "protects" instead?
That makes the intended relationship between the lock and the
tuple/relation/... much clearer. We'd then say

(A)
"Protected page number within the relation, or null if the lock
does not protect a tuple or relation page".

Another possibility is to make the relationship clearer by adding
the adjective "locked" before the locked thing, as in

(B)
"Locked page number within the relation, or null if the lock
is not on a tuple or relation page".

The latter also works "lock .. on .. " with
"locked object ... is ...", i.e.

(C)
"Locked page number within the relation, or null if the locked object
is not a tuple or relation page".

We could also get rid of the noun completely by saying

(D)
"Locked page number within the relation, or null if it isn't
a tuple or relation page that is locked".

I personally slightly favor (D).

best regards,
Florian Pflug

Florian Pflug wrote:
> On Jul13, 2011, at 17:44 , Tom Lane wrote:
> > Bruce Momjian <bruce(at)momjian(dot)us> writes:
> >> OK, I went with this wording, using "lock object is on" terminology.
> >> Applied patch attached --- adjustments welcomed.
> >
> > I think you misunderstood the suggestion. This is not an improvement,
> > it's just more confusion.
>
> FWIW, I agree. First, "lock object" seems redundant - you might just as
> well say simply "lock". This is different from "locked object" - there,
> the noun "object" servers as a dummy that gives the adjective "locked"
> something to refer to.

I would personally prefer "lock" rather than "lock object".

> Also, it now sounds as if we were talking about the storage
> location of the lock (as an entity in itself) in some of the sentences.
>
> Here's an example
>
> "Page number within the relation, or null if the lock object
> is not on a tuple or relation page".
>
> To me at least, that sounds as if the lock might somehow be stored
> on a "relation page".
>
> Maybe "on" is still too generic. What if we said "protects" instead?
> That makes the intended relationship between the lock and the
> tuple/relation/... much clearer. We'd then say
>
> (A)
> "Protected page number within the relation, or null if the lock
> does not protect a tuple or relation page".
>
> Another possibility is to make the relationship clearer by adding
> the adjective "locked" before the locked thing, as in
>
> (B)
> "Locked page number within the relation, or null if the lock
> is not on a tuple or relation page".

Yes, I like this --- putting the "Locked at the front". The old code
says things like "Page number within the relation" which is kind of
generic.

>
> The latter also works "lock .. on .. " with
> "locked object ... is ...", i.e.
>
> (C)
> "Locked page number within the relation, or null if the locked object
> is not a tuple or relation page".
>
> We could also get rid of the noun completely by saying
>
> (D)
> "Locked page number within the relation, or null if it isn't
> a tuple or relation page that is locked".

>
> I personally slightly favor (D).

Me too. Others?

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

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

Bruce Momjian <bruce(at)momjian(dot)us> writes:
> Tom Lane wrote:
>> I think you misunderstood the suggestion. This is not an improvement,
>> it's just more confusion.

> Well, I thought the "lock on" wording helped avoid the confusion but
> obviously I didn't understand more than that. We did have similar
> confusion when we clarified the locking C code. For me, "object" was
> the stumbler. Do you have any suggested wording? Everyone seems to
> agree it needs improvement.

Well, first, "lock object" is completely useless, it does not convey
more than "lock" does; and second, you've added confusion because the
very same sentences also use "object" to refer to the thing being
locked.

regards, tom lane

On 07/13/2011 12:31 PM, Tom Lane wrote:
> Bruce Momjian<bruce(at)momjian(dot)us> writes:
>> Tom Lane wrote:
>>> I think you misunderstood the suggestion. This is not an improvement,
>>> it's just more confusion.
>> Well, I thought the "lock on" wording helped avoid the confusion but
>> obviously I didn't understand more than that. We did have similar
>> confusion when we clarified the locking C code. For me, "object" was
>> the stumbler. Do you have any suggested wording? Everyone seems to
>> agree it needs improvement.
> Well, first, "lock object" is completely useless, it does not convey
> more than "lock" does; and second, you've added confusion because the
> very same sentences also use "object" to refer to the thing being
> locked.
>

Maybe "lock" for the lock itself and "lock target" for the thing locked,
or some such, would work.

I agree that "object" on its own is not a terribly helpful term. It's
too often shorthand for "whatever-it-is".

cheers

andrew

Florian Pflug wrote:
> We could also get rid of the noun completely by saying
>
> (D)
> "Locked page number within the relation, or null if it isn't
> a tuple or relation page that is locked".
>
> I personally slightly favor (D).

I don't think we can use "Locked" here because the lock might not be
granted.

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

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

Andrew Dunstan wrote:
>
>
> On 07/13/2011 12:31 PM, Tom Lane wrote:
> > Bruce Momjian<bruce(at)momjian(dot)us> writes:
> >> Tom Lane wrote:
> >>> I think you misunderstood the suggestion. This is not an improvement,
> >>> it's just more confusion.
> >> Well, I thought the "lock on" wording helped avoid the confusion but
> >> obviously I didn't understand more than that. We did have similar
> >> confusion when we clarified the locking C code. For me, "object" was
> >> the stumbler. Do you have any suggested wording? Everyone seems to
> >> agree it needs improvement.
> > Well, first, "lock object" is completely useless, it does not convey
> > more than "lock" does; and second, you've added confusion because the
> > very same sentences also use "object" to refer to the thing being
> > locked.
> >
>
>
> Maybe "lock" for the lock itself and "lock target" for the thing locked,
> or some such, would work.
>
> I agree that "object" on its own is not a terribly helpful term. It's
> too often shorthand for "whatever-it-is".

Agreed.

OK, new wording based on the comments above; attached.

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

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

On Jul13, 2011, at 21:08 , Bruce Momjian wrote:
> - OID of the database in which the object exists, or
> - zero if the object is a shared object, or
> - null if the lock object is on a transaction ID
> + OID of the database in which the lock target exists, or
> + zero if the lock is a shared object, or
> + null if the lock is on a transaction ID

This sounds good.

> + OID of the relation lock target, or null if the lock is not
> on a relation or part of a relation

That, however, not so much. "relation lock target" might easily
be interpreted as the "relation's lock target" or the
"relation lock's target" - at least by non-native speakers such
as myself. The same is true fro "transaction lock target" and
friends.

Can't we simply go with "Locked relation", "Locked transaction id"
and so on (as in my versions B,C and D up-thread)? I can't really
get excited about the slight imprecision caused by the fact that some
rows describe aspiring lock holders instead of current lock holders.
The existence of the "granted" column makes the situation pretty clear.

Plus, it's technically not even wrong - a process is waiting because
somebody else *is* actually holding a lock on the object. So
the tuple/transaction/... is, in fact, a "Locked tuple/transaction/..."

best regards,
Florian Pflug

Florian Pflug wrote:
> On Jul13, 2011, at 21:08 , Bruce Momjian wrote:
> > - OID of the database in which the object exists, or
> > - zero if the object is a shared object, or
> > - null if the lock object is on a transaction ID
> > + OID of the database in which the lock target exists, or
> > + zero if the lock is a shared object, or
> > + null if the lock is on a transaction ID
>
> This sounds good.
>
> > + OID of the relation lock target, or null if the lock is not
> > on a relation or part of a relation
>
> That, however, not so much. "relation lock target" might easily
> be interpreted as the "relation's lock target" or the
> "relation lock's target" - at least by non-native speakers such
> as myself. The same is true fro "transaction lock target" and
> friends.
>
> Can't we simply go with "Locked relation", "Locked transaction id"
> and so on (as in my versions B,C and D up-thread)? I can't really
> get excited about the slight imprecision caused by the fact that some
> rows describe aspiring lock holders instead of current lock holders.
> The existence of the "granted" column makes the situation pretty clear.
>
> Plus, it's technically not even wrong - a process is waiting because
> somebody else *is* actually holding a lock on the object. So
> the tuple/transaction/... is, in fact, a "Locked tuple/transaction/..."

I think it will be very confusing to have "locked" refer to the person
holding the lock while the row is based on who is waiting for it.

I reworded that line to:

+ OID of the relation of the lock target, or null if the lock is not

Update patch attached.

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

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

On Jul14, 2011, at 19:06 , Bruce Momjian wrote:
> Florian Pflug wrote:
>> On Jul13, 2011, at 21:08 , Bruce Momjian wrote:
>>> + OID of the relation lock target, or null if the lock is not
>>> on a relation or part of a relation
>>
>> That, however, not so much. "relation lock target" might easily
>> be interpreted as the "relation's lock target" or the
>> "relation lock's target" - at least by non-native speakers such
>> as myself. The same is true fro "transaction lock target" and
>> friends.
>>
>> Can't we simply go with "Locked relation", "Locked transaction id"
>> and so on (as in my versions B,C and D up-thread)? I can't really
>> get excited about the slight imprecision caused by the fact that some
>> rows describe aspiring lock holders instead of current lock holders.
>> The existence of the "granted" column makes the situation pretty clear.
>>
>> Plus, it's technically not even wrong - a process is waiting because
>> somebody else *is* actually holding a lock on the object. So
>> the tuple/transaction/... is, in fact, a "Locked tuple/transaction/..."
>
> I think it will be very confusing to have "locked" refer to the person
> holding the lock while the row is based on who is waiting for it.

I still believe the chance of confusion to be extremely small, but since
you feel otherwise, what about "Targeted" instead of "Locked". As in

OID of the relation targeted by the lock, or null if the lock does not
target a relation or part of a relation.

Page number within the relation targeted by the lock, or null if the
lock does not target a tuple or a relation page.

Virtual ID of the transaction targeted by the lock, or null if the lock
does not target a virtual transaction ID.

"Protected"/"protects" instead of "Targeted"/"targets" would also work.

Both avoid the imprecision of saying "Locked", and the ambiguity "on" -
which might either mean the physical location of the lock, or the object
its protecting/targeting.

> I reworded that line to:
>
> + OID of the relation of the lock target, or null if the lock is not

I'm not a huge fan of that. IMHO " .. of .. of .. " chains are hard to
read. Plus, there isn't such a thing as the "relation of a lock target" -
the relation *is* the lock target, not a part thereof.

best regards,
Florian Pflug

Florian Pflug wrote:
> I still believe the chance of confusion to be extremely small, but since
> you feel otherwise, what about "Targeted" instead of "Locked". As in
>
> OID of the relation targeted by the lock, or null if the lock does not
> target a relation or part of a relation.
>
> Page number within the relation targeted by the lock, or null if the
> lock does not target a tuple or a relation page.
>
> Virtual ID of the transaction targeted by the lock, or null if the lock
> does not target a virtual transaction ID.
>
> "Protected"/"protects" instead of "Targeted"/"targets" would also work.
>
> Both avoid the imprecision of saying "Locked", and the ambiguity "on" -
> which might either mean the physical location of the lock, or the object
> its protecting/targeting.
>
> > I reworded that line to:
> >
> > + OID of the relation of the lock target, or null if the lock is not
>
> I'm not a huge fan of that. IMHO " .. of .. of .. " chains are hard to
> read. Plus, there isn't such a thing as the "relation of a lock target" -
> the relation *is* the lock target, not a part thereof.

Agreed. I like "targeted by". New patch attached.

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

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

On Jul14, 2011, at 22:18 , Bruce Momjian wrote:
> ! OID of the database in which the lock target exists, or
> ! zero if the lock is a shared object, or
> ! null if the lock is on a transaction ID

For consistency, I think it should say "target" in the second part
of the sentence also now, instead of "lock ... on".

Updated patch attached. I tried to make the descriptions a
bit more consistent, replaced "object" by "target", and
added "targeted by" after the phrase which describes the
locked (or waited-for) object.

best regards,
Florian Pflug

diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
index d4a1d36..33be5d0 100644
*** a/doc/src/sgml/catalogs.sgml
--- b/doc/src/sgml/catalogs.sgml
***************
*** 6928,6936 ****
<entry><type>oid</type></entry>
<entry><literal><link linkend="catalog-pg-database"><structname>pg_database</structname></link>.oid</literal></entry>
<entry>
! OID of the database in which the object exists, or
! zero if the object is a shared object, or
! null if the object is a transaction ID
</entry>
</row>
<row>
--- 6928,6936 ----
<entry><type>oid</type></entry>
<entry><literal><link linkend="catalog-pg-database"><structname>pg_database</structname></link>.oid</literal></entry>
<entry>
! OID of the database in which the lock target exists, or
! zero if the target is a shared object, or
! null if the target is a transaction ID
</entry>
</row>
<row>
***************
*** 6938,6944 ****
<entry><type>oid</type></entry>
<entry><literal><link linkend="catalog-pg-class"><structname>pg_class</structname></link>.oid</literal></entry>
<entry>
! OID of the relation, or null if the object is not
a relation or part of a relation
</entry>
</row>
--- 6938,6944 ----
<entry><type>oid</type></entry>
<entry><literal><link linkend="catalog-pg-class"><structname>pg_class</structname></link>.oid</literal></entry>
<entry>
! OID of the relation targeted by the lock, or null if the target is not
a relation or part of a relation
</entry>
</row>
***************
*** 6947,6954 ****
<entry><type>integer</type></entry>
<entry></entry>
<entry>
! Page number within the relation, or null if the object
! is not a tuple or relation page
</entry>
</row>
<row>
--- 6947,6954 ----
<entry><type>integer</type></entry>
<entry></entry>
<entry>
! Page number targeted by the lock within the relation,
! or null if the target is not a relation page or tuple
</entry>
</row>
<row>
***************
*** 6956,6962 ****
<entry><type>smallint</type></entry>
<entry></entry>
<entry>
! Tuple number within the page, or null if the object is not a tuple
</entry>
</row>
<row>
--- 6956,6963 ----
<entry><type>smallint</type></entry>
<entry></entry>
<entry>
! Tuple number targeted by the lock within the page,
! or null if the target is not a tuple
</entry>
</row>
<row>
***************
*** 6964,6971 ****
<entry><type>text</type></entry>
<entry></entry>
<entry>
! Virtual ID of a transaction, or null if the object is not a
! virtual transaction ID
</entry>
</row>
<row>
--- 6965,6972 ----
<entry><type>text</type></entry>
<entry></entry>
<entry>
! Virtual ID of the transaction targeted by the lock,
! or null if the target is not a virtual transaction ID
</entry>
</row>
<row>
***************
*** 6973,6979 ****
<entry><type>xid</type></entry>
<entry></entry>
<entry>
! ID of a transaction, or null if the object is not a transaction ID
</entry>
</row>
<row>
--- 6974,6981 ----
<entry><type>xid</type></entry>
<entry></entry>
<entry>
! ID of the transaction targeted by the lock,
! or null if the target is not a transaction ID
</entry>
</row>
<row>
***************
*** 6981,6988 ****
<entry><type>oid</type></entry>
<entry><literal><link linkend="catalog-pg-class"><structname>pg_class</structname></link>.oid</literal></entry>
<entry>
! OID of the system catalog containing the object, or null if the
! object is not a general database object
</entry>
</row>
<row>
--- 6983,6990 ----
<entry><type>oid</type></entry>
<entry><literal><link linkend="catalog-pg-class"><structname>pg_class</structname></link>.oid</literal></entry>
<entry>
! OID of the system catalog containing the lock target, or null if the
! target is not a general database object
</entry>
</row>
<row>
***************
*** 6990,6997 ****
<entry><type>oid</type></entry>
<entry>any OID column</entry>
<entry>
! OID of the object within its system catalog, or null if the
! object is not a general database object.
For advisory locks it is used to distinguish the two key
spaces (1 for an int8 key, 2 for two int4 keys).
</entry>
--- 6992,6999 ----
<entry><type>oid</type></entry>
<entry>any OID column</entry>
<entry>
! OID of the lock target within its system catalog, or null if the
! target is not a general database object.
For advisory locks it is used to distinguish the two key
spaces (1 for an int8 key, 2 for two int4 keys).
</entry>
***************
*** 7001,7010 ****
<entry><type>smallint</type></entry>
<entry></entry>
<entry>
! For a table column, this is the column number (the
<structfield>classid</> and <structfield>objid</> refer to the
! table itself). For all other object types, this column is
! zero. Null if the object is not a general database object
</entry>
</row>
<row>
--- 7003,7013 ----
<entry><type>smallint</type></entry>
<entry></entry>
<entry>
! Column number targeted by the lock (the
<structfield>classid</> and <structfield>objid</> refer to the
! table itself),
! or zero if the target is some other general database object,
! or null if the target is not a general database object
</entry>
</row>
<row>

Looks good to me.

---------------------------------------------------------------------------

Florian Pflug wrote:
> On Jul14, 2011, at 22:18 , Bruce Momjian wrote:
> > ! OID of the database in which the lock target exists, or
> > ! zero if the lock is a shared object, or
> > ! null if the lock is on a transaction ID
>
> For consistency, I think it should say "target" in the second part
> of the sentence also now, instead of "lock ... on".
>
> Updated patch attached. I tried to make the descriptions a
> bit more consistent, replaced "object" by "target", and
> added "targeted by" after the phrase which describes the
> locked (or waited-for) object.
>
> best regards,
> Florian Pflug
>
> diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
> index d4a1d36..33be5d0 100644
> *** a/doc/src/sgml/catalogs.sgml
> --- b/doc/src/sgml/catalogs.sgml
> ***************
> *** 6928,6936 ****
> <entry><type>oid</type></entry>
> <entry><literal><link linkend="catalog-pg-database"><structname>pg_database</structname></link>.oid</literal></entry>
> <entry>
> ! OID of the database in which the object exists, or
> ! zero if the object is a shared object, or
> ! null if the object is a transaction ID
> </entry>
> </row>
> <row>
> --- 6928,6936 ----
> <entry><type>oid</type></entry>
> <entry><literal><link linkend="catalog-pg-database"><structname>pg_database</structname></link>.oid</literal></entry>
> <entry>
> ! OID of the database in which the lock target exists, or
> ! zero if the target is a shared object, or
> ! null if the target is a transaction ID
> </entry>
> </row>
> <row>
> ***************
> *** 6938,6944 ****
> <entry><type>oid</type></entry>
> <entry><literal><link linkend="catalog-pg-class"><structname>pg_class</structname></link>.oid</literal></entry>
> <entry>
> ! OID of the relation, or null if the object is not
> a relation or part of a relation
> </entry>
> </row>
> --- 6938,6944 ----
> <entry><type>oid</type></entry>
> <entry><literal><link linkend="catalog-pg-class"><structname>pg_class</structname></link>.oid</literal></entry>
> <entry>
> ! OID of the relation targeted by the lock, or null if the target is not
> a relation or part of a relation
> </entry>
> </row>
> ***************
> *** 6947,6954 ****
> <entry><type>integer</type></entry>
> <entry></entry>
> <entry>
> ! Page number within the relation, or null if the object
> ! is not a tuple or relation page
> </entry>
> </row>
> <row>
> --- 6947,6954 ----
> <entry><type>integer</type></entry>
> <entry></entry>
> <entry>
> ! Page number targeted by the lock within the relation,
> ! or null if the target is not a relation page or tuple
> </entry>
> </row>
> <row>
> ***************
> *** 6956,6962 ****
> <entry><type>smallint</type></entry>
> <entry></entry>
> <entry>
> ! Tuple number within the page, or null if the object is not a tuple
> </entry>
> </row>
> <row>
> --- 6956,6963 ----
> <entry><type>smallint</type></entry>
> <entry></entry>
> <entry>
> ! Tuple number targeted by the lock within the page,
> ! or null if the target is not a tuple
> </entry>
> </row>
> <row>
> ***************
> *** 6964,6971 ****
> <entry><type>text</type></entry>
> <entry></entry>
> <entry>
> ! Virtual ID of a transaction, or null if the object is not a
> ! virtual transaction ID
> </entry>
> </row>
> <row>
> --- 6965,6972 ----
> <entry><type>text</type></entry>
> <entry></entry>
> <entry>
> ! Virtual ID of the transaction targeted by the lock,
> ! or null if the target is not a virtual transaction ID
> </entry>
> </row>
> <row>
> ***************
> *** 6973,6979 ****
> <entry><type>xid</type></entry>
> <entry></entry>
> <entry>
> ! ID of a transaction, or null if the object is not a transaction ID
> </entry>
> </row>
> <row>
> --- 6974,6981 ----
> <entry><type>xid</type></entry>
> <entry></entry>
> <entry>
> ! ID of the transaction targeted by the lock,
> ! or null if the target is not a transaction ID
> </entry>
> </row>
> <row>
> ***************
> *** 6981,6988 ****
> <entry><type>oid</type></entry>
> <entry><literal><link linkend="catalog-pg-class"><structname>pg_class</structname></link>.oid</literal></entry>
> <entry>
> ! OID of the system catalog containing the object, or null if the
> ! object is not a general database object
> </entry>
> </row>
> <row>
> --- 6983,6990 ----
> <entry><type>oid</type></entry>
> <entry><literal><link linkend="catalog-pg-class"><structname>pg_class</structname></link>.oid</literal></entry>
> <entry>
> ! OID of the system catalog containing the lock target, or null if the
> ! target is not a general database object
> </entry>
> </row>
> <row>
> ***************
> *** 6990,6997 ****
> <entry><type>oid</type></entry>
> <entry>any OID column</entry>
> <entry>
> ! OID of the object within its system catalog, or null if the
> ! object is not a general database object.
> For advisory locks it is used to distinguish the two key
> spaces (1 for an int8 key, 2 for two int4 keys).
> </entry>
> --- 6992,6999 ----
> <entry><type>oid</type></entry>
> <entry>any OID column</entry>
> <entry>
> ! OID of the lock target within its system catalog, or null if the
> ! target is not a general database object.
> For advisory locks it is used to distinguish the two key
> spaces (1 for an int8 key, 2 for two int4 keys).
> </entry>
> ***************
> *** 7001,7010 ****
> <entry><type>smallint</type></entry>
> <entry></entry>
> <entry>
> ! For a table column, this is the column number (the
> <structfield>classid</> and <structfield>objid</> refer to the
> ! table itself). For all other object types, this column is
> ! zero. Null if the object is not a general database object
> </entry>
> </row>
> <row>
> --- 7003,7013 ----
> <entry><type>smallint</type></entry>
> <entry></entry>
> <entry>
> ! Column number targeted by the lock (the
> <structfield>classid</> and <structfield>objid</> refer to the
> ! table itself),
> ! or zero if the target is some other general database object,
> ! or null if the target is not a general database object
> </entry>
> </row>
> <row>

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

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

Thanks, applied.

---------------------------------------------------------------------------

Florian Pflug wrote:
> On Jul14, 2011, at 22:18 , Bruce Momjian wrote:
> > ! OID of the database in which the lock target exists, or
> > ! zero if the lock is a shared object, or
> > ! null if the lock is on a transaction ID
>
> For consistency, I think it should say "target" in the second part
> of the sentence also now, instead of "lock ... on".
>
> Updated patch attached. I tried to make the descriptions a
> bit more consistent, replaced "object" by "target", and
> added "targeted by" after the phrase which describes the
> locked (or waited-for) object.
>
> best regards,
> Florian Pflug
>
> diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
> index d4a1d36..33be5d0 100644
> *** a/doc/src/sgml/catalogs.sgml
> --- b/doc/src/sgml/catalogs.sgml
> ***************
> *** 6928,6936 ****
> <entry><type>oid</type></entry>
> <entry><literal><link linkend="catalog-pg-database"><structname>pg_database</structname></link>.oid</literal></entry>
> <entry>
> ! OID of the database in which the object exists, or
> ! zero if the object is a shared object, or
> ! null if the object is a transaction ID
> </entry>
> </row>
> <row>
> --- 6928,6936 ----
> <entry><type>oid</type></entry>
> <entry><literal><link linkend="catalog-pg-database"><structname>pg_database</structname></link>.oid</literal></entry>
> <entry>
> ! OID of the database in which the lock target exists, or
> ! zero if the target is a shared object, or
> ! null if the target is a transaction ID
> </entry>
> </row>
> <row>
> ***************
> *** 6938,6944 ****
> <entry><type>oid</type></entry>
> <entry><literal><link linkend="catalog-pg-class"><structname>pg_class</structname></link>.oid</literal></entry>
> <entry>
> ! OID of the relation, or null if the object is not
> a relation or part of a relation
> </entry>
> </row>
> --- 6938,6944 ----
> <entry><type>oid</type></entry>
> <entry><literal><link linkend="catalog-pg-class"><structname>pg_class</structname></link>.oid</literal></entry>
> <entry>
> ! OID of the relation targeted by the lock, or null if the target is not
> a relation or part of a relation
> </entry>
> </row>
> ***************
> *** 6947,6954 ****
> <entry><type>integer</type></entry>
> <entry></entry>
> <entry>
> ! Page number within the relation, or null if the object
> ! is not a tuple or relation page
> </entry>
> </row>
> <row>
> --- 6947,6954 ----
> <entry><type>integer</type></entry>
> <entry></entry>
> <entry>
> ! Page number targeted by the lock within the relation,
> ! or null if the target is not a relation page or tuple
> </entry>
> </row>
> <row>
> ***************
> *** 6956,6962 ****
> <entry><type>smallint</type></entry>
> <entry></entry>
> <entry>
> ! Tuple number within the page, or null if the object is not a tuple
> </entry>
> </row>
> <row>
> --- 6956,6963 ----
> <entry><type>smallint</type></entry>
> <entry></entry>
> <entry>
> ! Tuple number targeted by the lock within the page,
> ! or null if the target is not a tuple
> </entry>
> </row>
> <row>
> ***************
> *** 6964,6971 ****
> <entry><type>text</type></entry>
> <entry></entry>
> <entry>
> ! Virtual ID of a transaction, or null if the object is not a
> ! virtual transaction ID
> </entry>
> </row>
> <row>
> --- 6965,6972 ----
> <entry><type>text</type></entry>
> <entry></entry>
> <entry>
> ! Virtual ID of the transaction targeted by the lock,
> ! or null if the target is not a virtual transaction ID
> </entry>
> </row>
> <row>
> ***************
> *** 6973,6979 ****
> <entry><type>xid</type></entry>
> <entry></entry>
> <entry>
> ! ID of a transaction, or null if the object is not a transaction ID
> </entry>
> </row>
> <row>
> --- 6974,6981 ----
> <entry><type>xid</type></entry>
> <entry></entry>
> <entry>
> ! ID of the transaction targeted by the lock,
> ! or null if the target is not a transaction ID
> </entry>
> </row>
> <row>
> ***************
> *** 6981,6988 ****
> <entry><type>oid</type></entry>
> <entry><literal><link linkend="catalog-pg-class"><structname>pg_class</structname></link>.oid</literal></entry>
> <entry>
> ! OID of the system catalog containing the object, or null if the
> ! object is not a general database object
> </entry>
> </row>
> <row>
> --- 6983,6990 ----
> <entry><type>oid</type></entry>
> <entry><literal><link linkend="catalog-pg-class"><structname>pg_class</structname></link>.oid</literal></entry>
> <entry>
> ! OID of the system catalog containing the lock target, or null if the
> ! target is not a general database object
> </entry>
> </row>
> <row>
> ***************
> *** 6990,6997 ****
> <entry><type>oid</type></entry>
> <entry>any OID column</entry>
> <entry>
> ! OID of the object within its system catalog, or null if the
> ! object is not a general database object.
> For advisory locks it is used to distinguish the two key
> spaces (1 for an int8 key, 2 for two int4 keys).
> </entry>
> --- 6992,6999 ----
> <entry><type>oid</type></entry>
> <entry>any OID column</entry>
> <entry>
> ! OID of the lock target within its system catalog, or null if the
> ! target is not a general database object.
> For advisory locks it is used to distinguish the two key
> spaces (1 for an int8 key, 2 for two int4 keys).
> </entry>
> ***************
> *** 7001,7010 ****
> <entry><type>smallint</type></entry>
> <entry></entry>
> <entry>
> ! For a table column, this is the column number (the
> <structfield>classid</> and <structfield>objid</> refer to the
> ! table itself). For all other object types, this column is
> ! zero. Null if the object is not a general database object
> </entry>
> </row>
> <row>
> --- 7003,7013 ----
> <entry><type>smallint</type></entry>
> <entry></entry>
> <entry>
> ! Column number targeted by the lock (the
> <structfield>classid</> and <structfield>objid</> refer to the
> ! table itself),
> ! or zero if the target is some other general database object,
> ! or null if the target is not a general database object
> </entry>
> </row>
> <row>

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

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