Subject: advisory locks: documentation hint and feature request

From: "Marc Mamin" <[email-masked]>
Date: Mon, 7 Jan 2008 12:28:22 +0100

Hello,
 
 I have defined some functions to manage advisory locks in a more
restrictive way than the default usage.
 
 here my requirements:
 
 - a session cannot stack write locks 
 - a session cannot aquire a shared lock if it already holds the write
locks
 - there is a maximum allowed shared locks (per lock id).

As I coun't find a way to count all current share locks for a given key
I also added the restriction that a given session can not get more than
one instance of a given shared lock.
This is a "strange" restriction for share locks, but this fits to our
lock usage.

doing this, I missed an information in the documentation that would be
useful to add:

pg_locks columns definition
---------------------------
 
current definition:
 
objid : OID of the object within its system catalog, 
        or NULL if the object is not a general database object
        
to add: "For advisory locks it is used to distinguish  the two key
spaces (one int8 or two int4 keys)

Table 9-56. Advisory Lock Functions (8.3 Beta)
-----------------------------------
 current: (note that these two key spaces do not overlap)
 
 to add: "; The two key spaces are separated on the column objid in the
pg_locks view"

 
 Moreover I missed some function that would allow a cleaner
implementation of my features 
 (reducing the need to query the pg_locks view)
 
 For example:
  
 --current shared lock count (owned / all)
 pg_advisory_lock_shared_count_my(key bigint)
 pg_advisory_lock_shared_count_all(key bigint)

 --enforce exclusive locks so that they cannot be stacked
 pg_try_advisory_lock_single(key bigint)
 
 --enforce shared locks so that they cannot be acquired if the current
session already holds the exclusive lock
I guess this should be the dafault behaviour for
   pg_advisory_lock_shared (..) and pg_try_advisory_lock_shared (...)
 
 --and possibly define a max number of allowed shared locks (over all
sessions)
 pg_[try_]advisory_lock_shared_max(key bigint, max_count int)

regards,
 
Marc Mamin

---

From: Bruce Momjian <[email-masked]>
Date: Thu, 6 Mar 2008 13:50:36 -0500 (EST)

> pg_locks columns definition

I have added your suggested changes to the docs with the attached patch.
Thanks.

>  pg_try_advisory_lock_single(key bigint)

Sorry, I am afraid they would not have general-enough usefulness.

-- 
  Bruce Momjian  <[email-masked]>        http://momjian.us
  EnterpriseDB                             http://postgres.enterprisedb.com

  + If your life is a hard drive, Christ can be your backup. +
Index: doc/src/sgml/catalogs.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/catalogs.sgml,v
retrieving revision 2.161
diff -c -c -r2.161 catalogs.sgml
*** doc/src/sgml/catalogs.sgml	31 Jan 2008 18:40:02 -0000	2.161
--- doc/src/sgml/catalogs.sgml	6 Mar 2008 18:48:54 -0000
***************
*** 5691,5697 ****
        <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
        </entry>
       </row>
       <row>
--- 5691,5700 ----
        <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 (<literal>1</> for an int8 key, <literal>2</> for two
!        int4 keys).
        </entry>
       </row>
       <row>
Index: doc/src/sgml/func.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/func.sgml,v
retrieving revision 1.422
diff -c -c -r1.422 func.sgml
*** doc/src/sgml/func.sgml	3 Mar 2008 18:09:02 -0000	1.422
--- doc/src/sgml/func.sgml	6 Mar 2008 18:48:58 -0000
***************
*** 12378,12384 ****
     <para>
      <function>pg_advisory_lock</> locks an application-defined resource,
      which can be identified either by a single 64-bit key value or two
!     32-bit key values (note that these two key spaces do not overlap).  If
      another session already holds a lock on the same resource, the
      function will wait until the resource becomes available.  The lock
      is exclusive.  Multiple lock requests stack, so that if the same resource
--- 12378,12385 ----
     <para>
      <function>pg_advisory_lock</> locks an application-defined resource,
      which can be identified either by a single 64-bit key value or two
!     32-bit key values (note that these two key spaces do not overlap). 
!     The key type is specified in <literal>pg_locks.objid</>.  If
      another session already holds a lock on the same resource, the
      function will wait until the resource becomes available.  The lock
      is exclusive.  Multiple lock requests stack, so that if the same resource