granicus.if.org Git - postgresql/blob - src/include/storage/lock.h

   1 /*-------------------------------------------------------------------------
   2  *
   3  * lock.h
   4  *        POSTGRES low-level lock mechanism
   5  *
   6  *
   7  * Portions Copyright (c) 1996-2007, PostgreSQL Global Development Group
   8  * Portions Copyright (c) 1994, Regents of the University of California
   9  *
  10  * $PostgreSQL: pgsql/src/include/storage/lock.h,v 1.103 2007/01/05 22:19:58 momjian Exp $
  11  *
  12  *-------------------------------------------------------------------------
  13  */
  14 #ifndef LOCK_H_
  15 #define LOCK_H_
  16
  17 #include "nodes/pg_list.h"
  18 #include "storage/itemptr.h"
  19 #include "storage/lwlock.h"
  20 #include "storage/shmem.h"
  21
  22
  23 /* struct PGPROC is declared in proc.h, but must forward-reference it */
  24 typedef struct PGPROC PGPROC;
  25
  26 typedef struct PROC_QUEUE
  27 {
  28         SHM_QUEUE       links;                  /* head of list of PGPROC objects */
  29         int                     size;                   /* number of entries in list */
  30 } PROC_QUEUE;
  31
  32 /* GUC variables */
  33 extern int      max_locks_per_xact;
  34
  35 #ifdef LOCK_DEBUG
  36 extern int      Trace_lock_oidmin;
  37 extern bool Trace_locks;
  38 extern bool Trace_userlocks;
  39 extern int      Trace_lock_table;
  40 extern bool Debug_deadlocks;
  41 #endif   /* LOCK_DEBUG */
  42
  43
  44 /*
  45  * LOCKMODE is an integer (1..N) indicating a lock type.  LOCKMASK is a bit
  46  * mask indicating a set of held or requested lock types (the bit 1<<mode
  47  * corresponds to a particular lock mode).
  48  */
  49 typedef int LOCKMASK;
  50 typedef int LOCKMODE;
  51
  52 /* MAX_LOCKMODES cannot be larger than the # of bits in LOCKMASK */
  53 #define MAX_LOCKMODES           10
  54
  55 #define LOCKBIT_ON(lockmode) (1 << (lockmode))
  56 #define LOCKBIT_OFF(lockmode) (~(1 << (lockmode)))
  57
  58
  59 /*
  60  * This data structure defines the locking semantics associated with a
  61  * "lock method".  The semantics specify the meaning of each lock mode
  62  * (by defining which lock modes it conflicts with), and also whether locks
  63  * of this method are transactional (ie, are released at transaction end).
  64  * All of this data is constant and is kept in const tables.
  65  *
  66  * numLockModes -- number of lock modes (READ,WRITE,etc) that
  67  *              are defined in this lock method.  Must be less than MAX_LOCKMODES.
  68  *
  69  * transactional -- TRUE if locks are released automatically at xact end.
  70  *
  71  * conflictTab -- this is an array of bitmasks showing lock
  72  *              mode conflicts.  conflictTab[i] is a mask with the j-th bit
  73  *              turned on if lock modes i and j conflict.  Lock modes are
  74  *              numbered 1..numLockModes; conflictTab[0] is unused.
  75  *
  76  * lockModeNames -- ID strings for debug printouts.
  77  *
  78  * trace_flag -- pointer to GUC trace flag for this lock method.
  79  */
  80 typedef struct LockMethodData
  81 {
  82         int                     numLockModes;
  83         bool            transactional;
  84         const LOCKMASK *conflictTab;
  85         const char *const * lockModeNames;
  86         const bool *trace_flag;
  87 } LockMethodData;
  88
  89 typedef const LockMethodData *LockMethod;
  90
  91 /*
  92  * Lock methods are identified by LOCKMETHODID.  (Despite the declaration as
  93  * uint16, we are constrained to 256 lockmethods by the layout of LOCKTAG.)
  94  */
  95 typedef uint16 LOCKMETHODID;
  96
  97 /* These identify the known lock methods */
  98 #define DEFAULT_LOCKMETHOD      1
  99 #define USER_LOCKMETHOD         2
 100
 101 /*
 102  * These are the valid values of type LOCKMODE for all the standard lock
 103  * methods (both DEFAULT and USER).
 104  */
 105
 106 /* NoLock is not a lock mode, but a flag value meaning "don't get a lock" */
 107 #define NoLock                                  0
 108
 109 #define AccessShareLock                 1               /* SELECT */
 110 #define RowShareLock                    2               /* SELECT FOR UPDATE/FOR SHARE */
 111 #define RowExclusiveLock                3               /* INSERT, UPDATE, DELETE */
 112 #define ShareUpdateExclusiveLock 4              /* VACUUM (non-FULL),ANALYZE, CREATE
 113                                                                                  * INDEX CONCURRENTLY */
 114 #define ShareLock                               5               /* CREATE INDEX (WITHOUT CONCURRENTLY) */
 115 #define ShareRowExclusiveLock   6               /* like EXCLUSIVE MODE, but allows ROW
 116                                                                                  * SHARE */
 117 #define ExclusiveLock                   7               /* blocks ROW SHARE/SELECT...FOR
 118                                                                                  * UPDATE */
 119 #define AccessExclusiveLock             8               /* ALTER TABLE, DROP TABLE, VACUUM
 120                                                                                  * FULL, and unqualified LOCK TABLE */
 121
 122
 123 /*
 124  * LOCKTAG is the key information needed to look up a LOCK item in the
 125  * lock hashtable.      A LOCKTAG value uniquely identifies a lockable object.
 126  *
 127  * The LockTagType enum defines the different kinds of objects we can lock.
 128  * We can handle up to 256 different LockTagTypes.
 129  */
 130 typedef enum LockTagType
 131 {
 132         LOCKTAG_RELATION,                       /* whole relation */
 133         /* ID info for a relation is DB OID + REL OID; DB OID = 0 if shared */
 134         LOCKTAG_RELATION_EXTEND,        /* the right to extend a relation */
 135         /* same ID info as RELATION */
 136         LOCKTAG_PAGE,                           /* one page of a relation */
 137         /* ID info for a page is RELATION info + BlockNumber */
 138         LOCKTAG_TUPLE,                          /* one physical tuple */
 139         /* ID info for a tuple is PAGE info + OffsetNumber */
 140         LOCKTAG_TRANSACTION,            /* transaction (for waiting for xact done) */
 141         /* ID info for a transaction is its TransactionId */
 142         LOCKTAG_OBJECT,                         /* non-relation database object */
 143         /* ID info for an object is DB OID + CLASS OID + OBJECT OID + SUBID */
 144
 145         /*
 146          * Note: object ID has same representation as in pg_depend and
 147          * pg_description, but notice that we are constraining SUBID to 16 bits.
 148          * Also, we use DB OID = 0 for shared objects such as tablespaces.
 149          */
 150         LOCKTAG_USERLOCK,                       /* reserved for old contrib/userlock code */
 151         LOCKTAG_ADVISORY                        /* advisory user locks */
 152 } LockTagType;
 153
 154 /*
 155  * The LOCKTAG struct is defined with malice aforethought to fit into 16
 156  * bytes with no padding.  Note that this would need adjustment if we were
 157  * to widen Oid, BlockNumber, or TransactionId to more than 32 bits.
 158  *
 159  * We include lockmethodid in the locktag so that a single hash table in
 160  * shared memory can store locks of different lockmethods.
 161  */
 162 typedef struct LOCKTAG
 163 {
 164         uint32          locktag_field1; /* a 32-bit ID field */
 165         uint32          locktag_field2; /* a 32-bit ID field */
 166         uint32          locktag_field3; /* a 32-bit ID field */
 167         uint16          locktag_field4; /* a 16-bit ID field */
 168         uint8           locktag_type;   /* see enum LockTagType */
 169         uint8           locktag_lockmethodid;   /* lockmethod indicator */
 170 } LOCKTAG;
 171
 172 /*
 173  * These macros define how we map logical IDs of lockable objects into
 174  * the physical fields of LOCKTAG.      Use these to set up LOCKTAG values,
 175  * rather than accessing the fields directly.  Note multiple eval of target!
 176  */
 177 #define SET_LOCKTAG_RELATION(locktag,dboid,reloid) \
 178         ((locktag).locktag_field1 = (dboid), \
 179          (locktag).locktag_field2 = (reloid), \
 180          (locktag).locktag_field3 = 0, \
 181          (locktag).locktag_field4 = 0, \
 182          (locktag).locktag_type = LOCKTAG_RELATION, \
 183          (locktag).locktag_lockmethodid = DEFAULT_LOCKMETHOD)
 184
 185 #define SET_LOCKTAG_RELATION_EXTEND(locktag,dboid,reloid) \
 186         ((locktag).locktag_field1 = (dboid), \
 187          (locktag).locktag_field2 = (reloid), \
 188          (locktag).locktag_field3 = 0, \
 189          (locktag).locktag_field4 = 0, \
 190          (locktag).locktag_type = LOCKTAG_RELATION_EXTEND, \
 191          (locktag).locktag_lockmethodid = DEFAULT_LOCKMETHOD)
 192
 193 #define SET_LOCKTAG_PAGE(locktag,dboid,reloid,blocknum) \
 194         ((locktag).locktag_field1 = (dboid), \
 195          (locktag).locktag_field2 = (reloid), \
 196          (locktag).locktag_field3 = (blocknum), \
 197          (locktag).locktag_field4 = 0, \
 198          (locktag).locktag_type = LOCKTAG_PAGE, \
 199          (locktag).locktag_lockmethodid = DEFAULT_LOCKMETHOD)
 200
 201 #define SET_LOCKTAG_TUPLE(locktag,dboid,reloid,blocknum,offnum) \
 202         ((locktag).locktag_field1 = (dboid), \
 203          (locktag).locktag_field2 = (reloid), \
 204          (locktag).locktag_field3 = (blocknum), \
 205          (locktag).locktag_field4 = (offnum), \
 206          (locktag).locktag_type = LOCKTAG_TUPLE, \
 207          (locktag).locktag_lockmethodid = DEFAULT_LOCKMETHOD)
 208
 209 #define SET_LOCKTAG_TRANSACTION(locktag,xid) \
 210         ((locktag).locktag_field1 = (xid), \
 211          (locktag).locktag_field2 = 0, \
 212          (locktag).locktag_field3 = 0, \
 213          (locktag).locktag_field4 = 0, \
 214          (locktag).locktag_type = LOCKTAG_TRANSACTION, \
 215          (locktag).locktag_lockmethodid = DEFAULT_LOCKMETHOD)
 216
 217 #define SET_LOCKTAG_OBJECT(locktag,dboid,classoid,objoid,objsubid) \
 218         ((locktag).locktag_field1 = (dboid), \
 219          (locktag).locktag_field2 = (classoid), \
 220          (locktag).locktag_field3 = (objoid), \
 221          (locktag).locktag_field4 = (objsubid), \
 222          (locktag).locktag_type = LOCKTAG_OBJECT, \
 223          (locktag).locktag_lockmethodid = DEFAULT_LOCKMETHOD)
 224
 225 #define SET_LOCKTAG_ADVISORY(locktag,id1,id2,id3,id4) \
 226         ((locktag).locktag_field1 = (id1), \
 227          (locktag).locktag_field2 = (id2), \
 228          (locktag).locktag_field3 = (id3), \
 229          (locktag).locktag_field4 = (id4), \
 230          (locktag).locktag_type = LOCKTAG_ADVISORY, \
 231          (locktag).locktag_lockmethodid = USER_LOCKMETHOD)
 232
 233
 234 /*
 235  * Per-locked-object lock information:
 236  *
 237  * tag -- uniquely identifies the object being locked
 238  * grantMask -- bitmask for all lock types currently granted on this object.
 239  * waitMask -- bitmask for all lock types currently awaited on this object.
 240  * procLocks -- list of PROCLOCK objects for this lock.
 241  * waitProcs -- queue of processes waiting for this lock.
 242  * requested -- count of each lock type currently requested on the lock
 243  *              (includes requests already granted!!).
 244  * nRequested -- total requested locks of all types.
 245  * granted -- count of each lock type currently granted on the lock.
 246  * nGranted -- total granted locks of all types.
 247  *
 248  * Note: these counts count 1 for each backend.  Internally to a backend,
 249  * there may be multiple grabs on a particular lock, but this is not reflected
 250  * into shared memory.
 251  */
 252 typedef struct LOCK
 253 {
 254         /* hash key */
 255         LOCKTAG         tag;                    /* unique identifier of lockable object */
 256
 257         /* data */
 258         LOCKMASK        grantMask;              /* bitmask for lock types already granted */
 259         LOCKMASK        waitMask;               /* bitmask for lock types awaited */
 260         SHM_QUEUE       procLocks;              /* list of PROCLOCK objects assoc. with lock */
 261         PROC_QUEUE      waitProcs;              /* list of PGPROC objects waiting on lock */
 262         int                     requested[MAX_LOCKMODES];               /* counts of requested locks */
 263         int                     nRequested;             /* total of requested[] array */
 264         int                     granted[MAX_LOCKMODES]; /* counts of granted locks */
 265         int                     nGranted;               /* total of granted[] array */
 266 } LOCK;
 267
 268 #define LOCK_LOCKMETHOD(lock) ((LOCKMETHODID) (lock).tag.locktag_lockmethodid)
 269
 270
 271 /*
 272  * We may have several different backends holding or awaiting locks
 273  * on the same lockable object.  We need to store some per-holder/waiter
 274  * information for each such holder (or would-be holder).  This is kept in
 275  * a PROCLOCK struct.
 276  *
 277  * PROCLOCKTAG is the key information needed to look up a PROCLOCK item in the
 278  * proclock hashtable.  A PROCLOCKTAG value uniquely identifies the combination
 279  * of a lockable object and a holder/waiter for that object.  (We can use
 280  * pointers here because the PROCLOCKTAG need only be unique for the lifespan
 281  * of the PROCLOCK, and it will never outlive the lock or the proc.)
 282  *
 283  * Internally to a backend, it is possible for the same lock to be held
 284  * for different purposes: the backend tracks transaction locks separately
 285  * from session locks.  However, this is not reflected in the shared-memory
 286  * state: we only track which backend(s) hold the lock.  This is OK since a
 287  * backend can never block itself.
 288  *
 289  * The holdMask field shows the already-granted locks represented by this
 290  * proclock.  Note that there will be a proclock object, possibly with
 291  * zero holdMask, for any lock that the process is currently waiting on.
 292  * Otherwise, proclock objects whose holdMasks are zero are recycled
 293  * as soon as convenient.
 294  *
 295  * releaseMask is workspace for LockReleaseAll(): it shows the locks due
 296  * to be released during the current call.      This must only be examined or
 297  * set by the backend owning the PROCLOCK.
 298  *
 299  * Each PROCLOCK object is linked into lists for both the associated LOCK
 300  * object and the owning PGPROC object.  Note that the PROCLOCK is entered
 301  * into these lists as soon as it is created, even if no lock has yet been
 302  * granted.  A PGPROC that is waiting for a lock to be granted will also be
 303  * linked into the lock's waitProcs queue.
 304  */
 305 typedef struct PROCLOCKTAG
 306 {
 307         /* NB: we assume this struct contains no padding! */
 308         LOCK       *myLock;                     /* link to per-lockable-object information */
 309         PGPROC     *myProc;                     /* link to PGPROC of owning backend */
 310 } PROCLOCKTAG;
 311
 312 typedef struct PROCLOCK
 313 {
 314         /* tag */
 315         PROCLOCKTAG tag;                        /* unique identifier of proclock object */
 316
 317         /* data */
 318         LOCKMASK        holdMask;               /* bitmask for lock types currently held */
 319         LOCKMASK        releaseMask;    /* bitmask for lock types to be released */
 320         SHM_QUEUE       lockLink;               /* list link in LOCK's list of proclocks */
 321         SHM_QUEUE       procLink;               /* list link in PGPROC's list of proclocks */
 322 } PROCLOCK;
 323
 324 #define PROCLOCK_LOCKMETHOD(proclock) \
 325         LOCK_LOCKMETHOD(*((proclock).tag.myLock))
 326
 327 /*
 328  * Each backend also maintains a local hash table with information about each
 329  * lock it is currently interested in.  In particular the local table counts
 330  * the number of times that lock has been acquired.  This allows multiple
 331  * requests for the same lock to be executed without additional accesses to
 332  * shared memory.  We also track the number of lock acquisitions per
 333  * ResourceOwner, so that we can release just those locks belonging to a
 334  * particular ResourceOwner.
 335  */
 336 typedef struct LOCALLOCKTAG
 337 {
 338         LOCKTAG         lock;                   /* identifies the lockable object */
 339         LOCKMODE        mode;                   /* lock mode for this table entry */
 340 } LOCALLOCKTAG;
 341
 342 typedef struct LOCALLOCKOWNER
 343 {
 344         /*
 345          * Note: if owner is NULL then the lock is held on behalf of the session;
 346          * otherwise it is held on behalf of my current transaction.
 347          *
 348          * Must use a forward struct reference to avoid circularity.
 349          */
 350         struct ResourceOwnerData *owner;
 351         int                     nLocks;                 /* # of times held by this owner */
 352 } LOCALLOCKOWNER;
 353
 354 typedef struct LOCALLOCK
 355 {
 356         /* tag */
 357         LOCALLOCKTAG tag;                       /* unique identifier of locallock entry */
 358
 359         /* data */
 360         LOCK       *lock;                       /* associated LOCK object in shared mem */
 361         PROCLOCK   *proclock;           /* associated PROCLOCK object in shmem */
 362         uint32          hashcode;               /* copy of LOCKTAG's hash value */
 363         int                     nLocks;                 /* total number of times lock is held */
 364         int                     numLockOwners;  /* # of relevant ResourceOwners */
 365         int                     maxLockOwners;  /* allocated size of array */
 366         LOCALLOCKOWNER *lockOwners; /* dynamically resizable array */
 367 } LOCALLOCK;
 368
 369 #define LOCALLOCK_LOCKMETHOD(llock) ((llock).tag.lock.locktag_lockmethodid)
 370
 371
 372 /*
 373  * This struct holds information passed from lmgr internals to the lock
 374  * listing user-level functions (in lockfuncs.c).       For each PROCLOCK in
 375  * the system, copies of the PROCLOCK object and associated PGPROC and
 376  * LOCK objects are stored.  Note there will often be multiple copies
 377  * of the same PGPROC or LOCK --- to detect whether two are the same,
 378  * compare the PROCLOCK tag fields.
 379  */
 380 typedef struct LockData
 381 {
 382         int                     nelements;              /* The length of each of the arrays */
 383         PROCLOCK   *proclocks;
 384         PGPROC     *procs;
 385         LOCK       *locks;
 386 } LockData;
 387
 388
 389 /* Result codes for LockAcquire() */
 390 typedef enum
 391 {
 392         LOCKACQUIRE_NOT_AVAIL,          /* lock not available, and dontWait=true */
 393         LOCKACQUIRE_OK,                         /* lock successfully acquired */
 394         LOCKACQUIRE_ALREADY_HELD        /* incremented count for lock already held */
 395 } LockAcquireResult;
 396
 397
 398 /*
 399  * The lockmgr's shared hash tables are partitioned to reduce contention.
 400  * To determine which partition a given locktag belongs to, compute the tag's
 401  * hash code with LockTagHashCode(), then apply one of these macros.
 402  * NB: NUM_LOCK_PARTITIONS must be a power of 2!
 403  */
 404 #define LockHashPartition(hashcode) \
 405         ((hashcode) % NUM_LOCK_PARTITIONS)
 406 #define LockHashPartitionLock(hashcode) \
 407         ((LWLockId) (FirstLockMgrLock + LockHashPartition(hashcode)))
 408
 409
 410 /*
 411  * function prototypes
 412  */
 413 extern void InitLocks(void);
 414 extern LockMethod GetLocksMethodTable(const LOCK *lock);
 415 extern uint32 LockTagHashCode(const LOCKTAG *locktag);
 416 extern LockAcquireResult LockAcquire(const LOCKTAG *locktag,
 417                         LOCKMODE lockmode,
 418                         bool sessionLock,
 419                         bool dontWait);
 420 extern bool LockRelease(const LOCKTAG *locktag,
 421                         LOCKMODE lockmode, bool sessionLock);
 422 extern void LockReleaseAll(LOCKMETHODID lockmethodid, bool allLocks);
 423 extern void LockReleaseCurrentOwner(void);
 424 extern void LockReassignCurrentOwner(void);
 425 extern List *GetLockConflicts(const LOCKTAG *locktag, LOCKMODE lockmode);
 426 extern void AtPrepare_Locks(void);
 427 extern void PostPrepare_Locks(TransactionId xid);
 428 extern int LockCheckConflicts(LockMethod lockMethodTable,
 429                                    LOCKMODE lockmode,
 430                                    LOCK *lock, PROCLOCK *proclock, PGPROC *proc);
 431 extern void GrantLock(LOCK *lock, PROCLOCK *proclock, LOCKMODE lockmode);
 432 extern void GrantAwaitedLock(void);
 433 extern void RemoveFromWaitQueue(PGPROC *proc, uint32 hashcode);
 434 extern Size LockShmemSize(void);
 435 extern LockData *GetLockStatusData(void);
 436 extern const char *GetLockmodeName(LOCKMETHODID lockmethodid, LOCKMODE mode);
 437
 438 extern void lock_twophase_recover(TransactionId xid, uint16 info,
 439                                           void *recdata, uint32 len);
 440 extern void lock_twophase_postcommit(TransactionId xid, uint16 info,
 441                                                  void *recdata, uint32 len);
 442 extern void lock_twophase_postabort(TransactionId xid, uint16 info,
 443                                                 void *recdata, uint32 len);
 444
 445 extern bool DeadLockCheck(PGPROC *proc);
 446 extern void DeadLockReport(void);
 447 extern void RememberSimpleDeadLock(PGPROC *proc1,
 448                                            LOCKMODE lockmode,
 449                                            LOCK *lock,
 450                                            PGPROC *proc2);
 451 extern void InitDeadLockChecking(void);
 452
 453 #ifdef LOCK_DEBUG
 454 extern void DumpLocks(PGPROC *proc);
 455 extern void DumpAllLocks(void);
 456 #endif
 457
 458 #endif   /* LOCK_H */