Thread: 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@momjian.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@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. + diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml new file mode 100644 index d4a1d36..9119929 *** a/doc/src/sgml/catalogs.sgml --- b/doc/src/sgml/catalogs.sgml *************** *** 6964,6970 **** <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> --- 6964,6970 ---- <entry><type>text</type></entry> <entry></entry> <entry> ! Virtual ID of a transaction lock, or null if the lock object is not a virtual transaction ID </entry> </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> --- 6973,6979 ---- <entry><type>xid</type></entry> <entry></entry> <entry> ! ID of a transaction lock, or null if the lock object is not a transaction ID </entry> </row> <row>
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@phlo.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@phlo.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@phlo.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@phlo.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@momjian.us> http://momjian.us EnterpriseDB
http://enterprisedb.com
+ It's impossible for everything to be true. +
Tom Lane wrote: > Florian Pflug <fgp@phlo.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@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. +
Bruce Momjian <bruce@momjian.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@phlo.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 lockis 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@momjian.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@phlo.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@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. + diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml new file mode 100644 index d4a1d36..c5851af *** a/doc/src/sgml/catalogs.sgml --- b/doc/src/sgml/catalogs.sgml *************** *** 6930,6936 **** <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> --- 6930,6936 ---- <entry> 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 </entry> </row> <row> *************** *** 6938,6945 **** <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> <row> --- 6938,6945 ---- <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 lock object is not ! on a relation or part of a relation </entry> </row> <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 within the relation, or null if the lock object ! is not on a tuple or relation page </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 within the page, or null if the lock object is not ! on 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 a transaction lock, or null if the lock object is not ! on 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,6980 ---- <entry><type>xid</type></entry> <entry></entry> <entry> ! ID of a transaction lock, or null if the lock object is not on a transaction ID </entry> </row> <row> *************** *** 6982,6988 **** <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,6989 ---- <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 ! lock object is not on a general database object. </entry> </row> <row> *************** *** 6991,6997 **** <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,6998 ---- <entry>any OID column</entry> <entry> OID of the object within its system catalog, or null if the ! lock object is not on 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> *************** *** 7004,7010 **** 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> --- 7005,7011 ---- 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 lock object is not on a general database object. </entry> </row> <row>
Bruce Momjian <bruce@momjian.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@momjian.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@momjian.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@momjian.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@momjian.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@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. +
Bruce Momjian <bruce@momjian.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@momjian.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@momjian.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@momjian.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@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. + diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml index c5851af..eae8a7c 100644 --- a/doc/src/sgml/catalogs.sgml +++ b/doc/src/sgml/catalogs.sgml @@ -6928,9 +6928,9 @@ <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 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 </entry> </row> <row> @@ -6938,7 +6938,7 @@ <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 lock object is not + OID of the relation lock target, or null if the lock is not on a relation or part of a relation </entry> </row> @@ -6947,7 +6947,7 @@ <entry><type>integer</type></entry> <entry></entry> <entry> - Page number within the relation, or null if the lock object + Page number within the relation, or null if the lock is not on a tuple or relation page </entry> </row> @@ -6956,7 +6956,7 @@ <entry><type>smallint</type></entry> <entry></entry> <entry> - Tuple number within the page, or null if the lock object is not + Tuple number within the page, or null if the lock is not on a tuple </entry> </row> @@ -6965,7 +6965,7 @@ <entry><type>text</type></entry> <entry></entry> <entry> - Virtual ID of a transaction lock, or null if the lock object is not + Virtual ID of a transaction lock target, or null if the lock is not on a virtual transaction ID </entry> </row> @@ -6974,7 +6974,7 @@ <entry><type>xid</type></entry> <entry></entry> <entry> - ID of a transaction lock, or null if the lock object is not on a transaction ID + ID of a transaction lock target, or null if the lock is not on a transaction ID </entry> </row> <row> @@ -6982,8 +6982,8 @@ <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 - lock object is not on a general database object. + OID of the system catalog containing the lock target, or null if the + lock is not on a general database object. </entry> </row> <row> @@ -6992,7 +6992,7 @@ <entry>any OID column</entry> <entry> OID of the object within its system catalog, or null if the - lock object is not on a general database object. + lock is not on 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> @@ -7005,7 +7005,7 @@ 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 lock object is not on a general database object. + zero. Null if the lock is not on a general database object. </entry> </row> <row>
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@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. + diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml index c5851af..84c2257 100644 --- a/doc/src/sgml/catalogs.sgml +++ b/doc/src/sgml/catalogs.sgml @@ -6928,9 +6928,9 @@ <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 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 </entry> </row> <row> @@ -6938,7 +6938,7 @@ <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 lock object is not + OID of the relation of the lock target, or null if the lock is not on a relation or part of a relation </entry> </row> @@ -6947,7 +6947,7 @@ <entry><type>integer</type></entry> <entry></entry> <entry> - Page number within the relation, or null if the lock object + Page number within the relation, or null if the lock is not on a tuple or relation page </entry> </row> @@ -6956,7 +6956,7 @@ <entry><type>smallint</type></entry> <entry></entry> <entry> - Tuple number within the page, or null if the lock object is not + Tuple number within the page, or null if the lock is not on a tuple </entry> </row> @@ -6965,7 +6965,7 @@ <entry><type>text</type></entry> <entry></entry> <entry> - Virtual ID of a transaction lock, or null if the lock object is not + Virtual ID of a transaction lock target, or null if the lock is not on a virtual transaction ID </entry> </row> @@ -6974,7 +6974,7 @@ <entry><type>xid</type></entry> <entry></entry> <entry> - ID of a transaction lock, or null if the lock object is not on a transaction ID + ID of a transaction lock target, or null if the lock is not on a transaction ID </entry> </row> <row> @@ -6982,8 +6982,8 @@ <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 - lock object is not on a general database object. + OID of the system catalog containing the lock target, or null if the + lock is not on a general database object. </entry> </row> <row> @@ -6992,7 +6992,7 @@ <entry>any OID column</entry> <entry> OID of the object within its system catalog, or null if the - lock object is not on a general database object. + lock is not on 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> @@ -7005,7 +7005,7 @@ 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 lock object is not on a general database object. + zero. Null if the lock is not on a general database object. </entry> </row> <row>
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@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. + diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml new file mode 100644 index c5851af..6fa6fa9 *** 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 lock object is on 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 lock is a shared object, or ! null if the lock is on 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 lock object is not on 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 lock is not on a relation or part of a relation </entry> </row> *************** *** 6947,6953 **** <entry><type>integer</type></entry> <entry></entry> <entry> ! Page number within the relation, or null if the lock object is not on a tuple or relation page </entry> </row> --- 6947,6953 ---- <entry><type>integer</type></entry> <entry></entry> <entry> ! Page number within the relation targeted by the lock, or null if the lock is not on a tuple or relation page </entry> </row> *************** *** 6956,6963 **** <entry><type>smallint</type></entry> <entry></entry> <entry> ! Tuple number within the page, or null if the lock object is not ! on a tuple </entry> </row> <row> --- 6956,6963 ---- <entry><type>smallint</type></entry> <entry></entry> <entry> ! Tuple number within the page targeted by the lock, or null if ! the lock is not on a tuple </entry> </row> <row> *************** *** 6965,6971 **** <entry><type>text</type></entry> <entry></entry> <entry> ! Virtual ID of a transaction lock, or null if the lock object is not on a virtual transaction ID </entry> </row> --- 6965,6971 ---- <entry><type>text</type></entry> <entry></entry> <entry> ! Virtual ID of a transaction targeted by the lock, or null if the lock is not on a virtual transaction ID </entry> </row> *************** *** 6974,6980 **** <entry><type>xid</type></entry> <entry></entry> <entry> ! ID of a transaction lock, or null if the lock object is not on a transaction ID </entry> </row> <row> --- 6974,6981 ---- <entry><type>xid</type></entry> <entry></entry> <entry> ! ID of a transaction targeted by the lock, or null if the lock ! is not on a transaction ID </entry> </row> <row> *************** *** 6982,6989 **** <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 ! lock object is not on 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 targeted by the lock, or null if the ! lock is not on a general database object. </entry> </row> <row> *************** *** 6991,6998 **** <entry><type>oid</type></entry> <entry>any OID column</entry> <entry> ! OID of the object within its system catalog, or null if the ! lock object is not on 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 object within its system catalog targeted by the ! lock, or null if the lock is not on 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> *************** *** 7005,7011 **** 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 lock object is not on a general database object. </entry> </row> <row> --- 7006,7012 ---- 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 lock is not on a general database object. </entry> </row> <row>
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</>
referto 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@momjian.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@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. +