PostgreSQL Source Code  git master
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros
lwlock.h
Go to the documentation of this file.
1 /*-------------------------------------------------------------------------
2  *
3  * lwlock.h
4  * Lightweight lock manager
5  *
6  *
7  * Portions Copyright (c) 1996-2015, PostgreSQL Global Development Group
8  * Portions Copyright (c) 1994, Regents of the University of California
9  *
10  * src/include/storage/lwlock.h
11  *
12  *-------------------------------------------------------------------------
13  */
14 #ifndef LWLOCK_H
15 #define LWLOCK_H
16 
17 #ifdef FRONTEND
18 #error "lwlock.h may not be included from frontend code"
19 #endif
20 
21 #include "lib/ilist.h"
22 #include "storage/s_lock.h"
23 #include "port/atomics.h"
24 
25 struct PGPROC;
26 
27 /*
28  * It's occasionally necessary to identify a particular LWLock "by name"; e.g.
29  * because we wish to report the lock to dtrace. We could store a name or
30  * other identifying information in the lock itself, but since it's common
31  * to have many nearly-identical locks (e.g. one per buffer) this would end
32  * up wasting significant amounts of memory. Instead, each lwlock stores a
33  * tranche ID which tells us which array it's part of. Based on that, we can
34  * figure out where the lwlock lies within the array using the data structure
35  * shown below; the lock is then identified based on the tranche name and
36  * computed array index. We need the array stride because the array might not
37  * be an array of lwlocks, but rather some larger data structure that includes
38  * one or more lwlocks per element.
39  */
40 typedef struct LWLockTranche
41 {
42  const char *name;
43  void *array_base;
46 
47 /*
48  * Code outside of lwlock.c should not manipulate the contents of this
49  * structure directly, but we have to declare it here to allow LWLocks to be
50  * incorporated into other data structures.
51  */
52 typedef struct LWLock
53 {
54  slock_t mutex; /* Protects LWLock and queue of PGPROCs */
55  uint16 tranche; /* tranche ID */
56 
57  pg_atomic_uint32 state; /* state of exlusive/nonexclusive lockers */
58 #ifdef LOCK_DEBUG
59  pg_atomic_uint32 nwaiters; /* number of waiters */
60 #endif
61  dlist_head waiters; /* list of waiting PGPROCs */
62 #ifdef LOCK_DEBUG
63  struct PGPROC *owner; /* last exlusive owner of the lock */
64 #endif
65 } LWLock;
66 
67 /*
68  * Prior to PostgreSQL 9.4, every lightweight lock in the system was stored
69  * in a single array. For convenience and for compatibility with past
70  * releases, we still have a main array, but it's now also permissible to
71  * store LWLocks elsewhere in the main shared memory segment or in a dynamic
72  * shared memory segment. In the main array, we force the array stride to
73  * be a power of 2, which saves a few cycles in indexing, but more importantly
74  * also ensures that individual LWLocks don't cross cache line boundaries.
75  * This reduces cache contention problems, especially on AMD Opterons.
76  * (Of course, we have to also ensure that the array start address is suitably
77  * aligned.)
78  *
79  * On a 32-bit platforms a LWLock will these days fit into 16 bytes, but since
80  * that didn't use to be the case and cramming more lwlocks into a cacheline
81  * might be detrimental performancewise we still use 32 byte alignment
82  * there. So, both on 32 and 64 bit platforms, it should fit into 32 bytes
83  * unless slock_t is really big. We allow for that just in case.
84  */
85 #define LWLOCK_PADDED_SIZE (sizeof(LWLock) <= 32 ? 32 : 64)
86 
87 typedef union LWLockPadded
88 {
91 } LWLockPadded;
93 
94 /*
95  * Some commonly-used locks have predefined positions within MainLWLockArray;
96  * defining macros here makes it much easier to keep track of these. If you
97  * add a lock, add it to the end to avoid renumbering the existing locks;
98  * if you remove a lock, consider leaving a gap in the numbering sequence for
99  * the benefit of DTrace and other external debugging scripts.
100  */
101 /* 0 is available; was formerly BufFreelistLock */
102 #define ShmemIndexLock (&MainLWLockArray[1].lock)
103 #define OidGenLock (&MainLWLockArray[2].lock)
104 #define XidGenLock (&MainLWLockArray[3].lock)
105 #define ProcArrayLock (&MainLWLockArray[4].lock)
106 #define SInvalReadLock (&MainLWLockArray[5].lock)
107 #define SInvalWriteLock (&MainLWLockArray[6].lock)
108 #define WALBufMappingLock (&MainLWLockArray[7].lock)
109 #define WALWriteLock (&MainLWLockArray[8].lock)
110 #define ControlFileLock (&MainLWLockArray[9].lock)
111 #define CheckpointLock (&MainLWLockArray[10].lock)
112 #define CLogControlLock (&MainLWLockArray[11].lock)
113 #define SubtransControlLock (&MainLWLockArray[12].lock)
114 #define MultiXactGenLock (&MainLWLockArray[13].lock)
115 #define MultiXactOffsetControlLock (&MainLWLockArray[14].lock)
116 #define MultiXactMemberControlLock (&MainLWLockArray[15].lock)
117 #define RelCacheInitLock (&MainLWLockArray[16].lock)
118 #define CheckpointerCommLock (&MainLWLockArray[17].lock)
119 #define TwoPhaseStateLock (&MainLWLockArray[18].lock)
120 #define TablespaceCreateLock (&MainLWLockArray[19].lock)
121 #define BtreeVacuumLock (&MainLWLockArray[20].lock)
122 #define AddinShmemInitLock (&MainLWLockArray[21].lock)
123 #define AutovacuumLock (&MainLWLockArray[22].lock)
124 #define AutovacuumScheduleLock (&MainLWLockArray[23].lock)
125 #define SyncScanLock (&MainLWLockArray[24].lock)
126 #define RelationMappingLock (&MainLWLockArray[25].lock)
127 #define AsyncCtlLock (&MainLWLockArray[26].lock)
128 #define AsyncQueueLock (&MainLWLockArray[27].lock)
129 #define SerializableXactHashLock (&MainLWLockArray[28].lock)
130 #define SerializableFinishedListLock (&MainLWLockArray[29].lock)
131 #define SerializablePredicateLockListLock (&MainLWLockArray[30].lock)
132 #define OldSerXidLock (&MainLWLockArray[31].lock)
133 #define SyncRepLock (&MainLWLockArray[32].lock)
134 #define BackgroundWorkerLock (&MainLWLockArray[33].lock)
135 #define DynamicSharedMemoryControlLock (&MainLWLockArray[34].lock)
136 #define AutoFileLock (&MainLWLockArray[35].lock)
137 #define ReplicationSlotAllocationLock (&MainLWLockArray[36].lock)
138 #define ReplicationSlotControlLock (&MainLWLockArray[37].lock)
139 #define CommitTsControlLock (&MainLWLockArray[38].lock)
140 #define CommitTsLock (&MainLWLockArray[39].lock)
141 #define ReplicationOriginLock (&MainLWLockArray[40].lock)
142 
143 #define NUM_INDIVIDUAL_LWLOCKS 41
144 
145 /*
146  * It's a bit odd to declare NUM_BUFFER_PARTITIONS and NUM_LOCK_PARTITIONS
147  * here, but we need them to figure out offsets within MainLWLockArray, and
148  * having this file include lock.h or bufmgr.h would be backwards.
149  */
150 
151 /* Number of partitions of the shared buffer mapping hashtable */
152 #define NUM_BUFFER_PARTITIONS 128
153 
154 /* Number of partitions the shared lock tables are divided into */
155 #define LOG2_NUM_LOCK_PARTITIONS 4
156 #define NUM_LOCK_PARTITIONS (1 << LOG2_NUM_LOCK_PARTITIONS)
157 
158 /* Number of partitions the shared predicate lock tables are divided into */
159 #define LOG2_NUM_PREDICATELOCK_PARTITIONS 4
160 #define NUM_PREDICATELOCK_PARTITIONS (1 << LOG2_NUM_PREDICATELOCK_PARTITIONS)
161 
162 /* Offsets for various chunks of preallocated lwlocks. */
163 #define BUFFER_MAPPING_LWLOCK_OFFSET NUM_INDIVIDUAL_LWLOCKS
164 #define LOCK_MANAGER_LWLOCK_OFFSET \
165  (BUFFER_MAPPING_LWLOCK_OFFSET + NUM_BUFFER_PARTITIONS)
166 #define PREDICATELOCK_MANAGER_LWLOCK_OFFSET \
167  (LOCK_MANAGER_LWLOCK_OFFSET + NUM_LOCK_PARTITIONS)
168 #define NUM_FIXED_LWLOCKS \
169  (PREDICATELOCK_MANAGER_LWLOCK_OFFSET + NUM_PREDICATELOCK_PARTITIONS)
170 
171 typedef enum LWLockMode
172 {
175  LW_WAIT_UNTIL_FREE /* A special mode used in PGPROC->lwlockMode,
176  * when waiting for lock to become free. Not
177  * to be used as LWLockAcquire argument */
178 } LWLockMode;
179 
180 
181 #ifdef LOCK_DEBUG
182 extern bool Trace_lwlocks;
183 #endif
184 
185 extern bool LWLockAcquire(LWLock *lock, LWLockMode mode);
186 extern bool LWLockConditionalAcquire(LWLock *lock, LWLockMode mode);
187 extern bool LWLockAcquireOrWait(LWLock *lock, LWLockMode mode);
188 extern void LWLockRelease(LWLock *lock);
189 extern void LWLockReleaseClearVar(LWLock *lock, uint64 *valptr, uint64 val);
190 extern void LWLockReleaseAll(void);
191 extern bool LWLockHeldByMe(LWLock *lock);
192 
193 extern bool LWLockWaitForVar(LWLock *lock, uint64 *valptr, uint64 oldval, uint64 *newval);
194 extern void LWLockUpdateVar(LWLock *lock, uint64 *valptr, uint64 value);
195 
196 extern Size LWLockShmemSize(void);
197 extern void CreateLWLocks(void);
198 extern void InitLWLockAccess(void);
199 
200 /*
201  * The traditional method for obtaining an lwlock for use by an extension is
202  * to call RequestAddinLWLocks() during postmaster startup; this will reserve
203  * space for the indicated number of locks in MainLWLockArray. Subsequently,
204  * a lock can be allocated using LWLockAssign.
205  */
206 extern void RequestAddinLWLocks(int n);
207 extern LWLock *LWLockAssign(void);
208 
209 /*
210  * There is another, more flexible method of obtaining lwlocks. First, call
211  * LWLockNewTrancheId just once to obtain a tranche ID; this allocates from
212  * a shared counter. Next, each individual process using the tranche should
213  * call LWLockRegisterTranche() to associate that tranche ID with appropriate
214  * metadata. Finally, LWLockInitialize should be called just once per lwlock,
215  * passing the tranche ID as an argument.
216  *
217  * It may seem strange that each process using the tranche must register it
218  * separately, but dynamic shared memory segments aren't guaranteed to be
219  * mapped at the same address in all coordinating backends, so storing the
220  * registration in the main shared memory segment wouldn't work for that case.
221  */
222 extern int LWLockNewTrancheId(void);
223 extern void LWLockRegisterTranche(int tranche_id, LWLockTranche *tranche);
224 extern void LWLockInitialize(LWLock *lock, int tranche_id);
225 
226 /*
227  * Prior to PostgreSQL 9.4, we used an enum type called LWLockId to refer
228  * to LWLocks. New code should instead use LWLock *. However, for the
229  * convenience of third-party code, we include the following typedef.
230  */
231 typedef LWLock *LWLockId;
232 
233 #endif /* LWLOCK_H */
int slock_t
Definition: s_lock.h:911
bool LWLockHeldByMe(LWLock *lock)
Definition: lwlock.c:1648
Definition: lwlock.h:52
LWLock * LWLockId
Definition: lwlock.h:231
void LWLockRegisterTranche(int tranche_id, LWLockTranche *tranche)
Definition: lwlock.c:538
bool LWLockAcquireOrWait(LWLock *lock, LWLockMode mode)
Definition: lwlock.c:1130
Size LWLockShmemSize(void)
Definition: lwlock.c:401
LWLockMode
Definition: lwlock.h:171
void LWLockUpdateVar(LWLock *lock, uint64 *valptr, uint64 value)
Definition: lwlock.c:1460
void LWLockReleaseClearVar(LWLock *lock, uint64 *valptr, uint64 val)
Definition: lwlock.c:1598
struct LWLockTranche LWLockTranche
void LWLockInitialize(LWLock *lock, int tranche_id)
Definition: lwlock.c:562
void InitLWLockAccess(void)
Definition: lwlock.c:481
bool LWLockConditionalAcquire(LWLock *lock, LWLockMode mode)
Definition: lwlock.c:1075
pg_atomic_uint32 state
Definition: lwlock.h:57
void RequestAddinLWLocks(int n)
Definition: lwlock.c:389
int LWLockNewTrancheId(void)
Definition: lwlock.c:518
void LWLockReleaseAll(void)
Definition: lwlock.c:1630
#define PGDLLIMPORT
Definition: c.h:1032
const char * name
Definition: lwlock.h:42
Size array_stride
Definition: lwlock.h:44
unsigned short uint16
Definition: c.h:253
static struct @72 value
void CreateLWLocks(void)
Definition: lwlock.c:421
uint16 tranche
Definition: lwlock.h:55
bool LWLockAcquire(LWLock *lock, LWLockMode mode)
Definition: lwlock.c:905
LWLock lock
Definition: lwlock.h:89
void * array_base
Definition: lwlock.h:43
size_t Size
Definition: c.h:341
dlist_head waiters
Definition: lwlock.h:61
#define newval
PGDLLIMPORT LWLockPadded * MainLWLockArray
Definition: lwlock.c:131
bool LWLockWaitForVar(LWLock *lock, uint64 *valptr, uint64 oldval, uint64 *newval)
Definition: lwlock.c:1321
#define LWLOCK_PADDED_SIZE
Definition: lwlock.h:85
void LWLockRelease(LWLock *lock)
Definition: lwlock.c:1524
Definition: proc.h:83
char pad[LWLOCK_PADDED_SIZE]
Definition: lwlock.h:90
long val
Definition: informix.c:689
slock_t mutex
Definition: lwlock.h:54
struct LWLock LWLock
LWLock * LWLockAssign(void)
Definition: lwlock.c:497
union LWLockPadded LWLockPadded