1 /*-------------------------------------------------------------------------
4 * POSTGRES low-level lock mechanism
7 * Portions Copyright (c) 1996-2008, PostgreSQL Global Development Group
8 * Portions Copyright (c) 1994, Regents of the University of California
12 *-------------------------------------------------------------------------
17 #include "storage/backendid.h"
18 #include "storage/lwlock.h"
19 #include "storage/shmem.h"
22 /* struct PGPROC is declared in proc.h, but must forward-reference it */
23 typedef struct PGPROC PGPROC
;
25 typedef struct PROC_QUEUE
27 SHM_QUEUE links
; /* head of list of PGPROC objects */
28 int size
; /* number of entries in list */
32 extern int max_locks_per_xact
;
35 extern int Trace_lock_oidmin
;
36 extern bool Trace_locks
;
37 extern bool Trace_userlocks
;
38 extern int Trace_lock_table
;
39 extern bool Debug_deadlocks
;
40 #endif /* LOCK_DEBUG */
44 * Top-level transactions are identified by VirtualTransactionIDs comprising
45 * the BackendId of the backend running the xact, plus a locally-assigned
46 * LocalTransactionId. These are guaranteed unique over the short term,
47 * but will be reused after a database restart; hence they should never
50 * Note that struct VirtualTransactionId can not be assumed to be atomically
51 * assignable as a whole. However, type LocalTransactionId is assumed to
52 * be atomically assignable, and the backend ID doesn't change often enough
53 * to be a problem, so we can fetch or assign the two fields separately.
54 * We deliberately refrain from using the struct within PGPROC, to prevent
55 * coding errors from trying to use struct assignment with it; instead use
56 * GET_VXID_FROM_PGPROC().
60 BackendId backendId
; /* determined at backend startup */
61 LocalTransactionId localTransactionId
; /* backend-local transaction
63 } VirtualTransactionId
;
65 #define InvalidLocalTransactionId 0
66 #define LocalTransactionIdIsValid(lxid) ((lxid) != InvalidLocalTransactionId)
67 #define VirtualTransactionIdIsValid(vxid) \
68 (((vxid).backendId != InvalidBackendId) && \
69 LocalTransactionIdIsValid((vxid).localTransactionId))
70 #define GET_VXID_FROM_PGPROC(vxid, proc) \
71 ((vxid).backendId = (proc).backendId, \
72 (vxid).localTransactionId = (proc).lxid)
76 * LOCKMODE is an integer (1..N) indicating a lock type. LOCKMASK is a bit
77 * mask indicating a set of held or requested lock types (the bit 1<<mode
78 * corresponds to a particular lock mode).
83 /* MAX_LOCKMODES cannot be larger than the # of bits in LOCKMASK */
84 #define MAX_LOCKMODES 10
86 #define LOCKBIT_ON(lockmode) (1 << (lockmode))
87 #define LOCKBIT_OFF(lockmode) (~(1 << (lockmode)))
91 * This data structure defines the locking semantics associated with a
92 * "lock method". The semantics specify the meaning of each lock mode
93 * (by defining which lock modes it conflicts with), and also whether locks
94 * of this method are transactional (ie, are released at transaction end).
95 * All of this data is constant and is kept in const tables.
97 * numLockModes -- number of lock modes (READ,WRITE,etc) that
98 * are defined in this lock method. Must be less than MAX_LOCKMODES.
100 * transactional -- TRUE if locks are released automatically at xact end.
102 * conflictTab -- this is an array of bitmasks showing lock
103 * mode conflicts. conflictTab[i] is a mask with the j-th bit
104 * turned on if lock modes i and j conflict. Lock modes are
105 * numbered 1..numLockModes; conflictTab[0] is unused.
107 * lockModeNames -- ID strings for debug printouts.
109 * trace_flag -- pointer to GUC trace flag for this lock method.
111 typedef struct LockMethodData
115 const LOCKMASK
*conflictTab
;
116 const char *const * lockModeNames
;
117 const bool *trace_flag
;
120 typedef const LockMethodData
*LockMethod
;
123 * Lock methods are identified by LOCKMETHODID. (Despite the declaration as
124 * uint16, we are constrained to 256 lockmethods by the layout of LOCKTAG.)
126 typedef uint16 LOCKMETHODID
;
128 /* These identify the known lock methods */
129 #define DEFAULT_LOCKMETHOD 1
130 #define USER_LOCKMETHOD 2
133 * These are the valid values of type LOCKMODE for all the standard lock
134 * methods (both DEFAULT and USER).
137 /* NoLock is not a lock mode, but a flag value meaning "don't get a lock" */
140 #define AccessShareLock 1 /* SELECT */
141 #define RowShareLock 2 /* SELECT FOR UPDATE/FOR SHARE */
142 #define RowExclusiveLock 3 /* INSERT, UPDATE, DELETE */
143 #define ShareUpdateExclusiveLock 4 /* VACUUM (non-FULL),ANALYZE, CREATE
144 * INDEX CONCURRENTLY */
145 #define ShareLock 5 /* CREATE INDEX (WITHOUT CONCURRENTLY) */
146 #define ShareRowExclusiveLock 6 /* like EXCLUSIVE MODE, but allows ROW
148 #define ExclusiveLock 7 /* blocks ROW SHARE/SELECT...FOR
150 #define AccessExclusiveLock 8 /* ALTER TABLE, DROP TABLE, VACUUM
151 * FULL, and unqualified LOCK TABLE */
155 * LOCKTAG is the key information needed to look up a LOCK item in the
156 * lock hashtable. A LOCKTAG value uniquely identifies a lockable object.
158 * The LockTagType enum defines the different kinds of objects we can lock.
159 * We can handle up to 256 different LockTagTypes.
161 typedef enum LockTagType
163 LOCKTAG_RELATION
, /* whole relation */
164 /* ID info for a relation is DB OID + REL OID; DB OID = 0 if shared */
165 LOCKTAG_RELATION_EXTEND
, /* the right to extend a relation */
166 /* same ID info as RELATION */
167 LOCKTAG_PAGE
, /* one page of a relation */
168 /* ID info for a page is RELATION info + BlockNumber */
169 LOCKTAG_TUPLE
, /* one physical tuple */
170 /* ID info for a tuple is PAGE info + OffsetNumber */
171 LOCKTAG_TRANSACTION
, /* transaction (for waiting for xact done) */
172 /* ID info for a transaction is its TransactionId */
173 LOCKTAG_VIRTUALTRANSACTION
, /* virtual transaction (ditto) */
174 /* ID info for a virtual transaction is its VirtualTransactionId */
175 LOCKTAG_OBJECT
, /* non-relation database object */
176 /* ID info for an object is DB OID + CLASS OID + OBJECT OID + SUBID */
179 * Note: object ID has same representation as in pg_depend and
180 * pg_description, but notice that we are constraining SUBID to 16 bits.
181 * Also, we use DB OID = 0 for shared objects such as tablespaces.
183 LOCKTAG_USERLOCK
, /* reserved for old contrib/userlock code */
184 LOCKTAG_ADVISORY
/* advisory user locks */
187 #define LOCKTAG_LAST_TYPE LOCKTAG_ADVISORY
190 * The LOCKTAG struct is defined with malice aforethought to fit into 16
191 * bytes with no padding. Note that this would need adjustment if we were
192 * to widen Oid, BlockNumber, or TransactionId to more than 32 bits.
194 * We include lockmethodid in the locktag so that a single hash table in
195 * shared memory can store locks of different lockmethods.
197 typedef struct LOCKTAG
199 uint32 locktag_field1
; /* a 32-bit ID field */
200 uint32 locktag_field2
; /* a 32-bit ID field */
201 uint32 locktag_field3
; /* a 32-bit ID field */
202 uint16 locktag_field4
; /* a 16-bit ID field */
203 uint8 locktag_type
; /* see enum LockTagType */
204 uint8 locktag_lockmethodid
; /* lockmethod indicator */
208 * These macros define how we map logical IDs of lockable objects into
209 * the physical fields of LOCKTAG. Use these to set up LOCKTAG values,
210 * rather than accessing the fields directly. Note multiple eval of target!
212 #define SET_LOCKTAG_RELATION(locktag,dboid,reloid) \
213 ((locktag).locktag_field1 = (dboid), \
214 (locktag).locktag_field2 = (reloid), \
215 (locktag).locktag_field3 = 0, \
216 (locktag).locktag_field4 = 0, \
217 (locktag).locktag_type = LOCKTAG_RELATION, \
218 (locktag).locktag_lockmethodid = DEFAULT_LOCKMETHOD)
220 #define SET_LOCKTAG_RELATION_EXTEND(locktag,dboid,reloid) \
221 ((locktag).locktag_field1 = (dboid), \
222 (locktag).locktag_field2 = (reloid), \
223 (locktag).locktag_field3 = 0, \
224 (locktag).locktag_field4 = 0, \
225 (locktag).locktag_type = LOCKTAG_RELATION_EXTEND, \
226 (locktag).locktag_lockmethodid = DEFAULT_LOCKMETHOD)
228 #define SET_LOCKTAG_PAGE(locktag,dboid,reloid,blocknum) \
229 ((locktag).locktag_field1 = (dboid), \
230 (locktag).locktag_field2 = (reloid), \
231 (locktag).locktag_field3 = (blocknum), \
232 (locktag).locktag_field4 = 0, \
233 (locktag).locktag_type = LOCKTAG_PAGE, \
234 (locktag).locktag_lockmethodid = DEFAULT_LOCKMETHOD)
236 #define SET_LOCKTAG_TUPLE(locktag,dboid,reloid,blocknum,offnum) \
237 ((locktag).locktag_field1 = (dboid), \
238 (locktag).locktag_field2 = (reloid), \
239 (locktag).locktag_field3 = (blocknum), \
240 (locktag).locktag_field4 = (offnum), \
241 (locktag).locktag_type = LOCKTAG_TUPLE, \
242 (locktag).locktag_lockmethodid = DEFAULT_LOCKMETHOD)
244 #define SET_LOCKTAG_TRANSACTION(locktag,xid) \
245 ((locktag).locktag_field1 = (xid), \
246 (locktag).locktag_field2 = 0, \
247 (locktag).locktag_field3 = 0, \
248 (locktag).locktag_field4 = 0, \
249 (locktag).locktag_type = LOCKTAG_TRANSACTION, \
250 (locktag).locktag_lockmethodid = DEFAULT_LOCKMETHOD)
252 #define SET_LOCKTAG_VIRTUALTRANSACTION(locktag,vxid) \
253 ((locktag).locktag_field1 = (vxid).backendId, \
254 (locktag).locktag_field2 = (vxid).localTransactionId, \
255 (locktag).locktag_field3 = 0, \
256 (locktag).locktag_field4 = 0, \
257 (locktag).locktag_type = LOCKTAG_VIRTUALTRANSACTION, \
258 (locktag).locktag_lockmethodid = DEFAULT_LOCKMETHOD)
260 #define SET_LOCKTAG_OBJECT(locktag,dboid,classoid,objoid,objsubid) \
261 ((locktag).locktag_field1 = (dboid), \
262 (locktag).locktag_field2 = (classoid), \
263 (locktag).locktag_field3 = (objoid), \
264 (locktag).locktag_field4 = (objsubid), \
265 (locktag).locktag_type = LOCKTAG_OBJECT, \
266 (locktag).locktag_lockmethodid = DEFAULT_LOCKMETHOD)
268 #define SET_LOCKTAG_ADVISORY(locktag,id1,id2,id3,id4) \
269 ((locktag).locktag_field1 = (id1), \
270 (locktag).locktag_field2 = (id2), \
271 (locktag).locktag_field3 = (id3), \
272 (locktag).locktag_field4 = (id4), \
273 (locktag).locktag_type = LOCKTAG_ADVISORY, \
274 (locktag).locktag_lockmethodid = USER_LOCKMETHOD)
278 * Per-locked-object lock information:
280 * tag -- uniquely identifies the object being locked
281 * grantMask -- bitmask for all lock types currently granted on this object.
282 * waitMask -- bitmask for all lock types currently awaited on this object.
283 * procLocks -- list of PROCLOCK objects for this lock.
284 * waitProcs -- queue of processes waiting for this lock.
285 * requested -- count of each lock type currently requested on the lock
286 * (includes requests already granted!!).
287 * nRequested -- total requested locks of all types.
288 * granted -- count of each lock type currently granted on the lock.
289 * nGranted -- total granted locks of all types.
291 * Note: these counts count 1 for each backend. Internally to a backend,
292 * there may be multiple grabs on a particular lock, but this is not reflected
293 * into shared memory.
298 LOCKTAG tag
; /* unique identifier of lockable object */
301 LOCKMASK grantMask
; /* bitmask for lock types already granted */
302 LOCKMASK waitMask
; /* bitmask for lock types awaited */
303 SHM_QUEUE procLocks
; /* list of PROCLOCK objects assoc. with lock */
304 PROC_QUEUE waitProcs
; /* list of PGPROC objects waiting on lock */
305 int requested
[MAX_LOCKMODES
]; /* counts of requested locks */
306 int nRequested
; /* total of requested[] array */
307 int granted
[MAX_LOCKMODES
]; /* counts of granted locks */
308 int nGranted
; /* total of granted[] array */
311 #define LOCK_LOCKMETHOD(lock) ((LOCKMETHODID) (lock).tag.locktag_lockmethodid)
315 * We may have several different backends holding or awaiting locks
316 * on the same lockable object. We need to store some per-holder/waiter
317 * information for each such holder (or would-be holder). This is kept in
320 * PROCLOCKTAG is the key information needed to look up a PROCLOCK item in the
321 * proclock hashtable. A PROCLOCKTAG value uniquely identifies the combination
322 * of a lockable object and a holder/waiter for that object. (We can use
323 * pointers here because the PROCLOCKTAG need only be unique for the lifespan
324 * of the PROCLOCK, and it will never outlive the lock or the proc.)
326 * Internally to a backend, it is possible for the same lock to be held
327 * for different purposes: the backend tracks transaction locks separately
328 * from session locks. However, this is not reflected in the shared-memory
329 * state: we only track which backend(s) hold the lock. This is OK since a
330 * backend can never block itself.
332 * The holdMask field shows the already-granted locks represented by this
333 * proclock. Note that there will be a proclock object, possibly with
334 * zero holdMask, for any lock that the process is currently waiting on.
335 * Otherwise, proclock objects whose holdMasks are zero are recycled
336 * as soon as convenient.
338 * releaseMask is workspace for LockReleaseAll(): it shows the locks due
339 * to be released during the current call. This must only be examined or
340 * set by the backend owning the PROCLOCK.
342 * Each PROCLOCK object is linked into lists for both the associated LOCK
343 * object and the owning PGPROC object. Note that the PROCLOCK is entered
344 * into these lists as soon as it is created, even if no lock has yet been
345 * granted. A PGPROC that is waiting for a lock to be granted will also be
346 * linked into the lock's waitProcs queue.
348 typedef struct PROCLOCKTAG
350 /* NB: we assume this struct contains no padding! */
351 LOCK
*myLock
; /* link to per-lockable-object information */
352 PGPROC
*myProc
; /* link to PGPROC of owning backend */
355 typedef struct PROCLOCK
358 PROCLOCKTAG tag
; /* unique identifier of proclock object */
361 LOCKMASK holdMask
; /* bitmask for lock types currently held */
362 LOCKMASK releaseMask
; /* bitmask for lock types to be released */
363 SHM_QUEUE lockLink
; /* list link in LOCK's list of proclocks */
364 SHM_QUEUE procLink
; /* list link in PGPROC's list of proclocks */
367 #define PROCLOCK_LOCKMETHOD(proclock) \
368 LOCK_LOCKMETHOD(*((proclock).tag.myLock))
371 * Each backend also maintains a local hash table with information about each
372 * lock it is currently interested in. In particular the local table counts
373 * the number of times that lock has been acquired. This allows multiple
374 * requests for the same lock to be executed without additional accesses to
375 * shared memory. We also track the number of lock acquisitions per
376 * ResourceOwner, so that we can release just those locks belonging to a
377 * particular ResourceOwner.
379 typedef struct LOCALLOCKTAG
381 LOCKTAG lock
; /* identifies the lockable object */
382 LOCKMODE mode
; /* lock mode for this table entry */
385 typedef struct LOCALLOCKOWNER
388 * Note: if owner is NULL then the lock is held on behalf of the session;
389 * otherwise it is held on behalf of my current transaction.
391 * Must use a forward struct reference to avoid circularity.
393 struct ResourceOwnerData
*owner
;
394 int64 nLocks
; /* # of times held by this owner */
397 typedef struct LOCALLOCK
400 LOCALLOCKTAG tag
; /* unique identifier of locallock entry */
403 LOCK
*lock
; /* associated LOCK object in shared mem */
404 PROCLOCK
*proclock
; /* associated PROCLOCK object in shmem */
405 uint32 hashcode
; /* copy of LOCKTAG's hash value */
406 int64 nLocks
; /* total number of times lock is held */
407 int numLockOwners
; /* # of relevant ResourceOwners */
408 int maxLockOwners
; /* allocated size of array */
409 LOCALLOCKOWNER
*lockOwners
; /* dynamically resizable array */
412 #define LOCALLOCK_LOCKMETHOD(llock) ((llock).tag.lock.locktag_lockmethodid)
416 * This struct holds information passed from lmgr internals to the lock
417 * listing user-level functions (in lockfuncs.c). For each PROCLOCK in
418 * the system, copies of the PROCLOCK object and associated PGPROC and
419 * LOCK objects are stored. Note there will often be multiple copies
420 * of the same PGPROC or LOCK --- to detect whether two are the same,
421 * compare the PROCLOCK tag fields.
423 typedef struct LockData
425 int nelements
; /* The length of each of the arrays */
432 /* Result codes for LockAcquire() */
435 LOCKACQUIRE_NOT_AVAIL
, /* lock not available, and dontWait=true */
436 LOCKACQUIRE_OK
, /* lock successfully acquired */
437 LOCKACQUIRE_ALREADY_HELD
/* incremented count for lock already held */
440 /* Deadlock states identified by DeadLockCheck() */
443 DS_NOT_YET_CHECKED
, /* no deadlock check has run yet */
444 DS_NO_DEADLOCK
, /* no deadlock detected */
445 DS_SOFT_DEADLOCK
, /* deadlock avoided by queue rearrangement */
446 DS_HARD_DEADLOCK
, /* deadlock, no way out but ERROR */
447 DS_BLOCKED_BY_AUTOVACUUM
/* no deadlock; queue blocked by autovacuum
453 * The lockmgr's shared hash tables are partitioned to reduce contention.
454 * To determine which partition a given locktag belongs to, compute the tag's
455 * hash code with LockTagHashCode(), then apply one of these macros.
456 * NB: NUM_LOCK_PARTITIONS must be a power of 2!
458 #define LockHashPartition(hashcode) \
459 ((hashcode) % NUM_LOCK_PARTITIONS)
460 #define LockHashPartitionLock(hashcode) \
461 ((LWLockId) (FirstLockMgrLock + LockHashPartition(hashcode)))
465 * function prototypes
467 extern void InitLocks(void);
468 extern LockMethod
GetLocksMethodTable(const LOCK
*lock
);
469 extern uint32
LockTagHashCode(const LOCKTAG
*locktag
);
470 extern LockAcquireResult
LockAcquire(const LOCKTAG
*locktag
,
474 extern bool LockRelease(const LOCKTAG
*locktag
,
475 LOCKMODE lockmode
, bool sessionLock
);
476 extern void LockReleaseAll(LOCKMETHODID lockmethodid
, bool allLocks
);
477 extern void LockReleaseCurrentOwner(void);
478 extern void LockReassignCurrentOwner(void);
479 extern VirtualTransactionId
*GetLockConflicts(const LOCKTAG
*locktag
,
481 extern void AtPrepare_Locks(void);
482 extern void PostPrepare_Locks(TransactionId xid
);
483 extern int LockCheckConflicts(LockMethod lockMethodTable
,
485 LOCK
*lock
, PROCLOCK
*proclock
, PGPROC
*proc
);
486 extern void GrantLock(LOCK
*lock
, PROCLOCK
*proclock
, LOCKMODE lockmode
);
487 extern void GrantAwaitedLock(void);
488 extern void RemoveFromWaitQueue(PGPROC
*proc
, uint32 hashcode
);
489 extern Size
LockShmemSize(void);
490 extern LockData
*GetLockStatusData(void);
491 extern const char *GetLockmodeName(LOCKMETHODID lockmethodid
, LOCKMODE mode
);
493 extern void lock_twophase_recover(TransactionId xid
, uint16 info
,
494 void *recdata
, uint32 len
);
495 extern void lock_twophase_postcommit(TransactionId xid
, uint16 info
,
496 void *recdata
, uint32 len
);
497 extern void lock_twophase_postabort(TransactionId xid
, uint16 info
,
498 void *recdata
, uint32 len
);
500 extern DeadLockState
DeadLockCheck(PGPROC
*proc
);
501 extern PGPROC
*GetBlockingAutoVacuumPgproc(void);
502 extern void DeadLockReport(void);
503 extern void RememberSimpleDeadLock(PGPROC
*proc1
,
507 extern void InitDeadLockChecking(void);
510 extern void DumpLocks(PGPROC
*proc
);
511 extern void DumpAllLocks(void);