1 /*-------------------------------------------------------------------------
4 * Lightweight lock manager
7 * Portions Copyright (c) 1996-2014, PostgreSQL Global Development Group
8 * Portions Copyright (c) 1994, Regents of the University of California
10 * src/include/storage/lwlock.h
12 *-------------------------------------------------------------------------
17 #include "storage/s_lock.h"
22 * It's occasionally necessary to identify a particular LWLock "by name"; e.g.
23 * because we wish to report the lock to dtrace. We could store a name or
24 * other identifying information in the lock itself, but since it's common
25 * to have many nearly-identical locks (e.g. one per buffer) this would end
26 * up wasting significant amounts of memory. Instead, each lwlock stores a
27 * tranche ID which tells us which array it's part of. Based on that, we can
28 * figure out where the lwlock lies within the array using the data structure
29 * shown below; the lock is then identified based on the tranche name and
30 * computed array index. We need the array stride because the array might not
31 * be an array of lwlocks, but rather some larger data structure that includes
32 * one or more lwlocks per element.
34 typedef struct LWLockTranche
42 * Code outside of lwlock.c should not manipulate the contents of this
43 * structure directly, but we have to declare it here to allow LWLocks to be
44 * incorporated into other data structures.
48 slock_t mutex; /* Protects LWLock and queue of PGPROCs */
49 bool releaseOK; /* T if ok to release waiters */
50 char exclusive; /* # of exclusive holders (0 or 1) */
51 int shared; /* # of shared holders (0..MaxBackends) */
52 int tranche; /* tranche ID */
53 struct PGPROC *head; /* head of list of waiting PGPROCs */
54 struct PGPROC *tail; /* tail of list of waiting PGPROCs */
55 /* tail is undefined when head is NULL */
59 * Prior to PostgreSQL 9.4, every lightweight lock in the system was stored
60 * in a single array. For convenience and for compatibility with past
61 * releases, we still have a main array, but it's now also permissible to
62 * store LWLocks elsewhere in the main shared memory segment or in a dynamic
63 * shared memory segment. In the main array, we force the array stride to
64 * be a power of 2, which saves a few cycles in indexing, but more importantly
65 * also ensures that individual LWLocks don't cross cache line boundaries.
66 * This reduces cache contention problems, especially on AMD Opterons.
67 * (Of course, we have to also ensure that the array start address is suitably
70 * Even on a 32-bit platform, an lwlock will be more than 16 bytes, because
71 * it contains 2 integers and 2 pointers, plus other stuff. It should fit
72 * into 32 bytes, though, unless slock_t is really big. On a 64-bit platform,
73 * it should fit into 32 bytes unless slock_t is larger than 4 bytes. We
74 * allow for that just in case.
76 #define LWLOCK_PADDED_SIZE (sizeof(LWLock) <= 32 ? 32 : 64)
78 typedef union LWLockPadded
81 char pad[LWLOCK_PADDED_SIZE];
83 extern PGDLLIMPORT LWLockPadded *MainLWLockArray;
86 * Some commonly-used locks have predefined positions within MainLWLockArray;
87 * defining macros here makes it much easier to keep track of these. If you
88 * add a lock, add it to the end to avoid renumbering the existing locks;
89 * if you remove a lock, consider leaving a gap in the numbering sequence for
90 * the benefit of DTrace and other external debugging scripts.
92 #define BufFreelistLock (&MainLWLockArray[0].lock)
93 #define ShmemIndexLock (&MainLWLockArray[1].lock)
94 #define OidGenLock (&MainLWLockArray[2].lock)
95 #define XidGenLock (&MainLWLockArray[3].lock)
96 #define ProcArrayLock (&MainLWLockArray[4].lock)
97 #define SInvalReadLock (&MainLWLockArray[5].lock)
98 #define SInvalWriteLock (&MainLWLockArray[6].lock)
99 #define WALBufMappingLock (&MainLWLockArray[7].lock)
100 #define WALWriteLock (&MainLWLockArray[8].lock)
101 #define ControlFileLock (&MainLWLockArray[9].lock)
102 #define CheckpointLock (&MainLWLockArray[10].lock)
103 #define CLogControlLock (&MainLWLockArray[11].lock)
104 #define SubtransControlLock (&MainLWLockArray[12].lock)
105 #define MultiXactGenLock (&MainLWLockArray[13].lock)
106 #define MultiXactOffsetControlLock (&MainLWLockArray[14].lock)
107 #define MultiXactMemberControlLock (&MainLWLockArray[15].lock)
108 #define RelCacheInitLock (&MainLWLockArray[16].lock)
109 #define CheckpointerCommLock (&MainLWLockArray[17].lock)
110 #define TwoPhaseStateLock (&MainLWLockArray[18].lock)
111 #define TablespaceCreateLock (&MainLWLockArray[19].lock)
112 #define BtreeVacuumLock (&MainLWLockArray[20].lock)
113 #define AddinShmemInitLock (&MainLWLockArray[21].lock)
114 #define AutovacuumLock (&MainLWLockArray[22].lock)
115 #define AutovacuumScheduleLock (&MainLWLockArray[23].lock)
116 #define SyncScanLock (&MainLWLockArray[24].lock)
117 #define RelationMappingLock (&MainLWLockArray[25].lock)
118 #define AsyncCtlLock (&MainLWLockArray[26].lock)
119 #define AsyncQueueLock (&MainLWLockArray[27].lock)
120 #define SerializableXactHashLock (&MainLWLockArray[28].lock)
121 #define SerializableFinishedListLock (&MainLWLockArray[29].lock)
122 #define SerializablePredicateLockListLock (&MainLWLockArray[30].lock)
123 #define OldSerXidLock (&MainLWLockArray[31].lock)
124 #define SyncRepLock (&MainLWLockArray[32].lock)
125 #define BackgroundWorkerLock (&MainLWLockArray[33].lock)
126 #define DynamicSharedMemoryControlLock (&MainLWLockArray[34].lock)
127 #define AutoFileLock (&MainLWLockArray[35].lock)
128 #define ReplicationSlotAllocationLock (&MainLWLockArray[36].lock)
129 #define ReplicationSlotControlLock (&MainLWLockArray[37].lock)
130 #define NUM_INDIVIDUAL_LWLOCKS 38
133 * It's a bit odd to declare NUM_BUFFER_PARTITIONS and NUM_LOCK_PARTITIONS
134 * here, but we need them to figure out offsets within MainLWLockArray, and
135 * having this file include lock.h or bufmgr.h would be backwards.
138 /* Number of partitions of the shared buffer mapping hashtable */
139 #define NUM_BUFFER_PARTITIONS 16
141 /* Number of partitions the shared lock tables are divided into */
142 #define LOG2_NUM_LOCK_PARTITIONS 4
143 #define NUM_LOCK_PARTITIONS (1 << LOG2_NUM_LOCK_PARTITIONS)
145 /* Number of partitions the shared predicate lock tables are divided into */
146 #define LOG2_NUM_PREDICATELOCK_PARTITIONS 4
147 #define NUM_PREDICATELOCK_PARTITIONS (1 << LOG2_NUM_PREDICATELOCK_PARTITIONS)
149 /* Offsets for various chunks of preallocated lwlocks. */
150 #define BUFFER_MAPPING_LWLOCK_OFFSET NUM_INDIVIDUAL_LWLOCKS
151 #define LOCK_MANAGER_LWLOCK_OFFSET \
152 (BUFFER_MAPPING_LWLOCK_OFFSET + NUM_BUFFER_PARTITIONS)
153 #define PREDICATELOCK_MANAGER_LWLOCK_OFFSET \
154 (NUM_INDIVIDUAL_LWLOCKS + NUM_LOCK_PARTITIONS)
155 #define NUM_FIXED_LWLOCKS \
156 (PREDICATELOCK_MANAGER_LWLOCK_OFFSET + NUM_PREDICATELOCK_PARTITIONS)
158 typedef enum LWLockMode
162 LW_WAIT_UNTIL_FREE /* A special mode used in PGPROC->lwlockMode,
163 * when waiting for lock to become free. Not
164 * to be used as LWLockAcquire argument */
169 extern bool Trace_lwlocks;
172 extern bool LWLockAcquire(LWLock *lock, LWLockMode mode);
173 extern bool LWLockConditionalAcquire(LWLock *lock, LWLockMode mode);
174 extern bool LWLockAcquireOrWait(LWLock *lock, LWLockMode mode);
175 extern void LWLockRelease(LWLock *lock);
176 extern void LWLockReleaseAll(void);
177 extern bool LWLockHeldByMe(LWLock *lock);
179 extern bool LWLockAcquireWithVar(LWLock *lock, uint64 *valptr, uint64 val);
180 extern bool LWLockWaitForVar(LWLock *lock, uint64 *valptr, uint64 oldval, uint64 *newval);
181 extern void LWLockUpdateVar(LWLock *lock, uint64 *valptr, uint64 value);
183 extern Size LWLockShmemSize(void);
184 extern void CreateLWLocks(void);
187 * The traditional method for obtaining an lwlock for use by an extension is
188 * to call RequestAddinLWLocks() during postmaster startup; this will reserve
189 * space for the indicated number of locks in MainLWLockArray. Subsequently,
190 * a lock can be allocated using LWLockAssign.
192 extern void RequestAddinLWLocks(int n);
193 extern LWLock *LWLockAssign(void);
196 * There is another, more flexible method of obtaining lwlocks. First, call
197 * LWLockNewTrancheId just once to obtain a tranche ID; this allocates from
198 * a shared counter. Next, each individual process using the tranche should
199 * call LWLockRegisterTranche() to associate that tranche ID with appropriate
200 * metadata. Finally, LWLockInitialize should be called just once per lwlock,
201 * passing the tranche ID as an argument.
203 * It may seem strange that each process using the tranche must register it
204 * separately, but dynamic shared memory segments aren't guaranteed to be
205 * mapped at the same address in all coordinating backends, so storing the
206 * registration in the main shared memory segment wouldn't work for that case.
208 extern int LWLockNewTrancheId(void);
209 extern void LWLockRegisterTranche(int, LWLockTranche *);
210 extern void LWLockInitialize(LWLock *, int tranche_id);
213 * Prior to PostgreSQL 9.4, we used an enum type called LWLockId to refer
214 * to LWLocks. New code should instead use LWLock *. However, for the
215 * convenience of third-party code, we include the following typedef.
217 typedef LWLock *LWLockId;
219 #endif /* LWLOCK_H */