Re: Need help understanding pg_locks - Mailing list pgsql-hackers

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>