User lock specification
=======================

The mechanics of user-locks are provided by the backend as discussed
in src/backend/storage/lmgr/lock.c and src/backend/storage/lmgr/README.
The comments in lock.c also show how lock tags are constructed from
user parameters. (Note that prior to 8.1, only the low 16 bits of the
"group" parameter were used.)

Userlocks always use USER_LOCKMETHOD, InvalidTransactionId and
dontWait == true; i.e. they are nonblocking, don't conflict with
real locks and aren't associated with a transaction.

The module is to provide the following SQL-callable functions:

user_lock(group int4, id int4, lockmode int4) returns int4

  Obtains a lock on the tag (group,id) using the specified lockmode
  (which is given as an integer, it's up to the caller to know what
  that means). returns 1 on success else 0

user_unlock(group int4, id int4, lockmode int4) returns int4

  Releases a lock obtained with user_lock. Returns 1 if such a lock
  existed, else 0

user_write_lock(group int4, id int4) returns int4
user_write_unlock(group int4, id int4) returns int4
user_write_lock(group int4, id oid) returns int4
user_write_unlock(group int4, id oid) returns int4

  Obtains/releases a lock on (group,id) using Exclusive mode. There is
  no difference between user_write_lock(1,1) and user_write_lock(1,1::oid),
  they lock the same thing.

user_write_lock_oid(id oid) returns int4
user_write_unlock_oid(id oid) returns int4
user_write_lock_oid(id int4) returns int4
user_write_unlock_oid(id int4) returns int4

  Obtains/releases a lock on (0,id) using Exclusive mode.

user_unlock_all() returns int4

  Release all userlocks held by the current session. Returns 1 on
  success (whether or not any locks were found) and 0 on failure.