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-2016, 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 "storage/proclist_types.h"
22 #include "storage/s_lock.h"
23 #include "port/atomics.h"
24 
25 struct PGPROC;
26 
27 /*
28  * Prior to PostgreSQL 9.4, every lightweight lock in the system was stored
29  * in a single array. For convenience and for compatibility with past
30  * releases, we still have a main array, but it's now also permissible to
31  * store LWLocks elsewhere in the main shared memory segment or in a dynamic
32  * shared memory segment. Each array of lwlocks forms a separate "tranche".
33  *
34  * It's occasionally necessary to identify a particular LWLock "by name"; e.g.
35  * because we wish to report the lock to dtrace. We could store a name or
36  * other identifying information in the lock itself, but since it's common
37  * to have many nearly-identical locks (e.g. one per buffer) this would end
38  * up wasting significant amounts of memory. Instead, each lwlock stores a
39  * tranche ID which tells us which array it's part of. Based on that, we can
40  * figure out where the lwlock lies within the array using the data structure
41  * shown below; the lock is then identified based on the tranche name and
42  * computed array index. We need the array stride because the array might not
43  * be an array of lwlocks, but rather some larger data structure that includes
44  * one or more lwlocks per element.
45  */
46 typedef struct LWLockTranche
47 {
48  const char *name;
49  void *array_base;
52 
53 /*
54  * Code outside of lwlock.c should not manipulate the contents of this
55  * structure directly, but we have to declare it here to allow LWLocks to be
56  * incorporated into other data structures.
57  */
58 typedef struct LWLock
59 {
60  uint16 tranche; /* tranche ID */
61  pg_atomic_uint32 state; /* state of exclusive/nonexclusive lockers */
62  proclist_head waiters; /* list of waiting PGPROCs */
63 #ifdef LOCK_DEBUG
64  pg_atomic_uint32 nwaiters; /* number of waiters */
65  struct PGPROC *owner; /* last exclusive owner of the lock */
66 #endif
67 } LWLock;
68 
69 /*
70  * In most cases, it's desirable to force each tranche of LWLocks to be aligned
71  * on a cache line boundary and make the array stride a power of 2. This saves
72  * a few cycles in indexing, but more importantly ensures that individual
73  * LWLocks don't cross cache line boundaries. This reduces cache contention
74  * problems, especially on AMD Opterons. In some cases, it's useful to add
75  * even more padding so that each LWLock takes up an entire cache line; this is
76  * useful, for example, in the main LWLock array, where the overall number of
77  * locks is small but some are heavily contended.
78  *
79  * When allocating a tranche that contains data other than LWLocks, it is
80  * probably best to include a bare LWLock and then pad the resulting structure
81  * as necessary for performance. For an array that contains only LWLocks,
82  * LWLockMinimallyPadded can be used for cases where we just want to ensure
83  * that we don't cross cache line boundaries within a single lock, while
84  * LWLockPadded can be used for cases where we want each lock to be an entire
85  * cache line.
86  *
87  * On 32-bit platforms, an LWLockMinimallyPadded might actually contain more
88  * than the absolute minimum amount of padding required to keep a lock from
89  * crossing a cache line boundary, because an unpadded LWLock might fit into
90  * 16 bytes. We ignore that possibility when determining the minimal amount
91  * of padding. Older releases had larger LWLocks, so 32 really was the
92  * minimum, and packing them in tighter might hurt performance.
93  *
94  * LWLOCK_MINIMAL_SIZE should be 32 on basically all common platforms, but
95  * because slock_t is more than 2 bytes on some obscure platforms, we allow
96  * for the possibility that it might be 64.
97  */
98 #define LWLOCK_PADDED_SIZE PG_CACHE_LINE_SIZE
99 #define LWLOCK_MINIMAL_SIZE (sizeof(LWLock) <= 32 ? 32 : 64)
100 
101 /* LWLock, padded to a full cache line size */
102 typedef union LWLockPadded
103 {
106 } LWLockPadded;
107 
108 /* LWLock, minimally padded */
110 {
114 
116 extern char *MainLWLockNames[];
117 
118 /* struct for storing named tranche information */
119 typedef struct NamedLWLockTranche
120 {
124 
127 
128 /* Names for fixed lwlocks */
129 #include "storage/lwlocknames.h"
130 
131 /*
132  * It's a bit odd to declare NUM_BUFFER_PARTITIONS and NUM_LOCK_PARTITIONS
133  * here, but we need them to figure out offsets within MainLWLockArray, and
134  * having this file include lock.h or bufmgr.h would be backwards.
135  */
136 
137 /* Number of partitions of the shared buffer mapping hashtable */
138 #define NUM_BUFFER_PARTITIONS 128
139 
140 /* Number of partitions the shared lock tables are divided into */
141 #define LOG2_NUM_LOCK_PARTITIONS 4
142 #define NUM_LOCK_PARTITIONS (1 << LOG2_NUM_LOCK_PARTITIONS)
143 
144 /* Number of partitions the shared predicate lock tables are divided into */
145 #define LOG2_NUM_PREDICATELOCK_PARTITIONS 4
146 #define NUM_PREDICATELOCK_PARTITIONS (1 << LOG2_NUM_PREDICATELOCK_PARTITIONS)
147 
148 /* Offsets for various chunks of preallocated lwlocks. */
149 #define BUFFER_MAPPING_LWLOCK_OFFSET NUM_INDIVIDUAL_LWLOCKS
150 #define LOCK_MANAGER_LWLOCK_OFFSET \
151  (BUFFER_MAPPING_LWLOCK_OFFSET + NUM_BUFFER_PARTITIONS)
152 #define PREDICATELOCK_MANAGER_LWLOCK_OFFSET \
153  (LOCK_MANAGER_LWLOCK_OFFSET + NUM_LOCK_PARTITIONS)
154 #define NUM_FIXED_LWLOCKS \
155  (PREDICATELOCK_MANAGER_LWLOCK_OFFSET + NUM_PREDICATELOCK_PARTITIONS)
156 
157 typedef enum LWLockMode
158 {
161  LW_WAIT_UNTIL_FREE /* A special mode used in PGPROC->lwlockMode,
162  * when waiting for lock to become free. Not
163  * to be used as LWLockAcquire argument */
164 } LWLockMode;
165 
166 
167 #ifdef LOCK_DEBUG
168 extern bool Trace_lwlocks;
169 #endif
170 
171 extern bool LWLockAcquire(LWLock *lock, LWLockMode mode);
172 extern bool LWLockConditionalAcquire(LWLock *lock, LWLockMode mode);
173 extern bool LWLockAcquireOrWait(LWLock *lock, LWLockMode mode);
174 extern void LWLockRelease(LWLock *lock);
175 extern void LWLockReleaseClearVar(LWLock *lock, uint64 *valptr, uint64 val);
176 extern void LWLockReleaseAll(void);
177 extern bool LWLockHeldByMe(LWLock *lock);
178 extern bool LWLockHeldByMeInMode(LWLock *lock, LWLockMode mode);
179 
180 extern bool LWLockWaitForVar(LWLock *lock, uint64 *valptr, uint64 oldval, uint64 *newval);
181 extern void LWLockUpdateVar(LWLock *lock, uint64 *valptr, uint64 value);
182 
183 extern Size LWLockShmemSize(void);
184 extern void CreateLWLocks(void);
185 extern void InitLWLockAccess(void);
186 
187 extern const char *GetLWLockIdentifier(uint32 classId, uint16 eventId);
188 
189 /*
190  * Extensions (or core code) can obtain an LWLocks by calling
191  * RequestNamedLWLockTranche() during postmaster startup. Subsequently,
192  * call GetNamedLWLockTranche() to obtain a pointer to an array containing
193  * the number of LWLocks requested.
194  */
195 extern void RequestNamedLWLockTranche(const char *tranche_name, int num_lwlocks);
196 extern LWLockPadded *GetNamedLWLockTranche(const char *tranche_name);
197 
198 /*
199  * There is another, more flexible method of obtaining lwlocks. First, call
200  * LWLockNewTrancheId just once to obtain a tranche ID; this allocates from
201  * a shared counter. Next, each individual process using the tranche should
202  * call LWLockRegisterTranche() to associate that tranche ID with appropriate
203  * metadata. Finally, LWLockInitialize should be called just once per lwlock,
204  * passing the tranche ID as an argument.
205  *
206  * It may seem strange that each process using the tranche must register it
207  * separately, but dynamic shared memory segments aren't guaranteed to be
208  * mapped at the same address in all coordinating backends, so storing the
209  * registration in the main shared memory segment wouldn't work for that case.
210  */
211 extern int LWLockNewTrancheId(void);
212 extern void LWLockRegisterTranche(int tranche_id, LWLockTranche *tranche);
213 extern void LWLockInitialize(LWLock *lock, int tranche_id);
214 
215 /*
216  * We reserve a few predefined tranche IDs. A call to LWLockNewTrancheId
217  * will never return a value less than LWTRANCHE_FIRST_USER_DEFINED.
218  */
219 typedef enum BuiltinTrancheIds
220 {
240 
241 /*
242  * Prior to PostgreSQL 9.4, we used an enum type called LWLockId to refer
243  * to LWLocks. New code should instead use LWLock *. However, for the
244  * convenience of third-party code, we include the following typedef.
245  */
246 typedef LWLock *LWLockId;
247 
248 #endif /* LWLOCK_H */
bool LWLockHeldByMe(LWLock *lock)
Definition: lwlock.c:1887
Definition: lwlock.h:58
LWLock * LWLockId
Definition: lwlock.h:246
char pad[LWLOCK_MINIMAL_SIZE]
Definition: lwlock.h:112
void LWLockRegisterTranche(int tranche_id, LWLockTranche *tranche)
Definition: lwlock.c:636
bool LWLockAcquireOrWait(LWLock *lock, LWLockMode mode)
Definition: lwlock.c:1391
const char * GetLWLockIdentifier(uint32 classId, uint16 eventId)
Definition: lwlock.c:753
Size LWLockShmemSize(void)
Definition: lwlock.c:380
LWLockMode
Definition: lwlock.h:157
void LWLockUpdateVar(LWLock *lock, uint64 *valptr, uint64 value)
Definition: lwlock.c:1717
void LWLockReleaseClearVar(LWLock *lock, uint64 *valptr, uint64 val)
Definition: lwlock.c:1844
bool LWLockHeldByMeInMode(LWLock *lock, LWLockMode mode)
Definition: lwlock.c:1905
struct LWLockTranche LWLockTranche
proclist_head waiters
Definition: lwlock.h:62
void LWLockInitialize(LWLock *lock, int tranche_id)
Definition: lwlock.c:712
void InitLWLockAccess(void)
Definition: lwlock.c:569
bool LWLockConditionalAcquire(LWLock *lock, LWLockMode mode)
Definition: lwlock.c:1336
pg_atomic_uint32 state
Definition: lwlock.h:61
struct NamedLWLockTranche NamedLWLockTranche
int LWLockNewTrancheId(void)
Definition: lwlock.c:616
void LWLockReleaseAll(void)
Definition: lwlock.c:1870
#define PGDLLIMPORT
Definition: c.h:1059
const char * name
Definition: lwlock.h:48
LWLockTranche lwLockTranche
Definition: lwlock.h:121
Size array_stride
Definition: lwlock.h:50
unsigned short uint16
Definition: c.h:264
#define LWLOCK_MINIMAL_SIZE
Definition: lwlock.h:99
void CreateLWLocks(void)
Definition: lwlock.c:412
union LWLockMinimallyPadded LWLockMinimallyPadded
unsigned int uint32
Definition: c.h:265
uint16 tranche
Definition: lwlock.h:60
PGDLLIMPORT NamedLWLockTranche * NamedLWLockTrancheArray
Definition: lwlock.c:164
bool LWLockAcquire(LWLock *lock, LWLockMode mode)
Definition: lwlock.c:1164
static struct @73 value
LWLock lock
Definition: lwlock.h:104
void * array_base
Definition: lwlock.h:49
size_t Size
Definition: c.h:352
#define newval
char * MainLWLockNames[]
BuiltinTrancheIds
Definition: lwlock.h:219
PGDLLIMPORT LWLockPadded * MainLWLockArray
Definition: lwlock.c:129
void RequestNamedLWLockTranche(const char *tranche_name, int num_lwlocks)
Definition: lwlock.c:672
bool LWLockWaitForVar(LWLock *lock, uint64 *valptr, uint64 oldval, uint64 *newval)
Definition: lwlock.c:1576
#define LWLOCK_PADDED_SIZE
Definition: lwlock.h:98
void LWLockRelease(LWLock *lock)
Definition: lwlock.c:1771
Definition: proc.h:84
char pad[LWLOCK_PADDED_SIZE]
Definition: lwlock.h:105
LWLockPadded * GetNamedLWLockTranche(const char *tranche_name)
Definition: lwlock.c:585
long val
Definition: informix.c:689
struct LWLock LWLock
union LWLockPadded LWLockPadded
PGDLLIMPORT int NamedLWLockTrancheRequests
Definition: lwlock.c:162