PostgreSQL Source Code  git master
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-2020, 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 "port/atomics.h"
22 #include "storage/proclist_types.h"
23 
24 struct PGPROC;
25 
26 /*
27  * Code outside of lwlock.c should not manipulate the contents of this
28  * structure directly, but we have to declare it here to allow LWLocks to be
29  * incorporated into other data structures.
30  */
31 typedef struct LWLock
32 {
33  uint16 tranche; /* tranche ID */
34  pg_atomic_uint32 state; /* state of exclusive/nonexclusive lockers */
35  proclist_head waiters; /* list of waiting PGPROCs */
36 #ifdef LOCK_DEBUG
37  pg_atomic_uint32 nwaiters; /* number of waiters */
38  struct PGPROC *owner; /* last exclusive owner of the lock */
39 #endif
40 } LWLock;
41 
42 /*
43  * In most cases, it's desirable to force each tranche of LWLocks to be aligned
44  * on a cache line boundary and make the array stride a power of 2. This saves
45  * a few cycles in indexing, but more importantly ensures that individual
46  * LWLocks don't cross cache line boundaries. This reduces cache contention
47  * problems, especially on AMD Opterons. In some cases, it's useful to add
48  * even more padding so that each LWLock takes up an entire cache line; this is
49  * useful, for example, in the main LWLock array, where the overall number of
50  * locks is small but some are heavily contended.
51  *
52  * When allocating a tranche that contains data other than LWLocks, it is
53  * probably best to include a bare LWLock and then pad the resulting structure
54  * as necessary for performance. For an array that contains only LWLocks,
55  * LWLockMinimallyPadded can be used for cases where we just want to ensure
56  * that we don't cross cache line boundaries within a single lock, while
57  * LWLockPadded can be used for cases where we want each lock to be an entire
58  * cache line.
59  *
60  * An LWLockMinimallyPadded might contain more than the absolute minimum amount
61  * of padding required to keep a lock from crossing a cache line boundary,
62  * because an unpadded LWLock will normally fit into 16 bytes. We ignore that
63  * possibility when determining the minimal amount of padding. Older releases
64  * had larger LWLocks, so 32 really was the minimum, and packing them in
65  * tighter might hurt performance.
66  *
67  * LWLOCK_MINIMAL_SIZE should be 32 on basically all common platforms, but
68  * because pg_atomic_uint32 is more than 4 bytes on some obscure platforms, we
69  * allow for the possibility that it might be 64. Even on those platforms,
70  * we probably won't exceed 32 bytes unless LOCK_DEBUG is defined.
71  */
72 #define LWLOCK_PADDED_SIZE PG_CACHE_LINE_SIZE
73 #define LWLOCK_MINIMAL_SIZE (sizeof(LWLock) <= 32 ? 32 : 64)
74 
75 /* LWLock, padded to a full cache line size */
76 typedef union LWLockPadded
77 {
79  char pad[LWLOCK_PADDED_SIZE];
80 } LWLockPadded;
81 
82 /* LWLock, minimally padded */
83 typedef union LWLockMinimallyPadded
84 {
88 
90 
91 /* struct for storing named tranche information */
92 typedef struct NamedLWLockTranche
93 {
94  int trancheId;
95  char *trancheName;
97 
100 
101 /* Names for fixed lwlocks */
102 #include "storage/lwlocknames.h"
103 
104 /*
105  * It's a bit odd to declare NUM_BUFFER_PARTITIONS and NUM_LOCK_PARTITIONS
106  * here, but we need them to figure out offsets within MainLWLockArray, and
107  * having this file include lock.h or bufmgr.h would be backwards.
108  */
109 
110 /* Number of partitions of the shared buffer mapping hashtable */
111 #define NUM_BUFFER_PARTITIONS 128
112 
113 /* Number of partitions the shared lock tables are divided into */
114 #define LOG2_NUM_LOCK_PARTITIONS 4
115 #define NUM_LOCK_PARTITIONS (1 << LOG2_NUM_LOCK_PARTITIONS)
116 
117 /* Number of partitions the shared predicate lock tables are divided into */
118 #define LOG2_NUM_PREDICATELOCK_PARTITIONS 4
119 #define NUM_PREDICATELOCK_PARTITIONS (1 << LOG2_NUM_PREDICATELOCK_PARTITIONS)
120 
121 /* Offsets for various chunks of preallocated lwlocks. */
122 #define BUFFER_MAPPING_LWLOCK_OFFSET NUM_INDIVIDUAL_LWLOCKS
123 #define LOCK_MANAGER_LWLOCK_OFFSET \
124  (BUFFER_MAPPING_LWLOCK_OFFSET + NUM_BUFFER_PARTITIONS)
125 #define PREDICATELOCK_MANAGER_LWLOCK_OFFSET \
126  (LOCK_MANAGER_LWLOCK_OFFSET + NUM_LOCK_PARTITIONS)
127 #define NUM_FIXED_LWLOCKS \
128  (PREDICATELOCK_MANAGER_LWLOCK_OFFSET + NUM_PREDICATELOCK_PARTITIONS)
129 
130 typedef enum LWLockMode
131 {
134  LW_WAIT_UNTIL_FREE /* A special mode used in PGPROC->lwWaitMode,
135  * when waiting for lock to become free. Not
136  * to be used as LWLockAcquire argument */
137 } LWLockMode;
138 
139 
140 #ifdef LOCK_DEBUG
141 extern bool Trace_lwlocks;
142 #endif
143 
144 extern bool LWLockAcquire(LWLock *lock, LWLockMode mode);
145 extern bool LWLockConditionalAcquire(LWLock *lock, LWLockMode mode);
146 extern bool LWLockAcquireOrWait(LWLock *lock, LWLockMode mode);
147 extern void LWLockRelease(LWLock *lock);
148 extern void LWLockReleaseClearVar(LWLock *lock, uint64 *valptr, uint64 val);
149 extern void LWLockReleaseAll(void);
150 extern bool LWLockHeldByMe(LWLock *lock);
151 extern bool LWLockHeldByMeInMode(LWLock *lock, LWLockMode mode);
152 
153 extern bool LWLockWaitForVar(LWLock *lock, uint64 *valptr, uint64 oldval, uint64 *newval);
154 extern void LWLockUpdateVar(LWLock *lock, uint64 *valptr, uint64 value);
155 
156 extern Size LWLockShmemSize(void);
157 extern void CreateLWLocks(void);
158 extern void InitLWLockAccess(void);
159 
160 extern const char *GetLWLockIdentifier(uint32 classId, uint16 eventId);
161 
162 /*
163  * Extensions (or core code) can obtain an LWLocks by calling
164  * RequestNamedLWLockTranche() during postmaster startup. Subsequently,
165  * call GetNamedLWLockTranche() to obtain a pointer to an array containing
166  * the number of LWLocks requested.
167  */
168 extern void RequestNamedLWLockTranche(const char *tranche_name, int num_lwlocks);
169 extern LWLockPadded *GetNamedLWLockTranche(const char *tranche_name);
170 
171 /*
172  * There is another, more flexible method of obtaining lwlocks. First, call
173  * LWLockNewTrancheId just once to obtain a tranche ID; this allocates from
174  * a shared counter. Next, each individual process using the tranche should
175  * call LWLockRegisterTranche() to associate that tranche ID with a name.
176  * Finally, LWLockInitialize should be called just once per lwlock, passing
177  * the tranche ID as an argument.
178  *
179  * It may seem strange that each process using the tranche must register it
180  * separately, but dynamic shared memory segments aren't guaranteed to be
181  * mapped at the same address in all coordinating backends, so storing the
182  * registration in the main shared memory segment wouldn't work for that case.
183  */
184 extern int LWLockNewTrancheId(void);
185 extern void LWLockRegisterTranche(int tranche_id, const char *tranche_name);
186 extern void LWLockInitialize(LWLock *lock, int tranche_id);
187 
188 /*
189  * Every tranche ID less than NUM_INDIVIDUAL_LWLOCKS is reserved; also,
190  * we reserve additional tranche IDs for builtin tranches not included in
191  * the set of individual LWLocks. A call to LWLockNewTrancheId will never
192  * return a value less than LWTRANCHE_FIRST_USER_DEFINED.
193  */
194 typedef enum BuiltinTrancheIds
195 {
196  LWTRANCHE_XACT_BUFFER = NUM_INDIVIDUAL_LWLOCKS,
223 
224 /*
225  * Prior to PostgreSQL 9.4, we used an enum type called LWLockId to refer
226  * to LWLocks. New code should instead use LWLock *. However, for the
227  * convenience of third-party code, we include the following typedef.
228  */
229 typedef LWLock *LWLockId;
230 
231 #endif /* LWLOCK_H */
bool LWLockHeldByMe(LWLock *lock)
Definition: lwlock.c:1928
static PgChecksumMode mode
Definition: pg_checksums.c:61
Definition: lwlock.h:31
LWLock * LWLockId
Definition: lwlock.h:229
bool LWLockAcquireOrWait(LWLock *lock, LWLockMode mode)
Definition: lwlock.c:1435
const char * GetLWLockIdentifier(uint32 classId, uint16 eventId)
Definition: lwlock.c:809
Size LWLockShmemSize(void)
Definition: lwlock.c:435
LWLockMode
Definition: lwlock.h:130
void LWLockUpdateVar(LWLock *lock, uint64 *valptr, uint64 value)
Definition: lwlock.c:1758
static struct @142 value
void LWLockReleaseClearVar(LWLock *lock, uint64 *valptr, uint64 val)
Definition: lwlock.c:1885
bool LWLockHeldByMeInMode(LWLock *lock, LWLockMode mode)
Definition: lwlock.c:1946
proclist_head waiters
Definition: lwlock.h:35
void LWLockInitialize(LWLock *lock, int tranche_id)
Definition: lwlock.c:745
void InitLWLockAccess(void)
Definition: lwlock.c:583
bool LWLockConditionalAcquire(LWLock *lock, LWLockMode mode)
Definition: lwlock.c:1380
pg_atomic_uint32 state
Definition: lwlock.h:34
struct NamedLWLockTranche NamedLWLockTranche
int LWLockNewTrancheId(void)
Definition: lwlock.c:629
void LWLockReleaseAll(void)
Definition: lwlock.c:1911
#define PGDLLIMPORT
Definition: c.h:1257
unsigned short uint16
Definition: c.h:373
#define LWLOCK_MINIMAL_SIZE
Definition: lwlock.h:73
void CreateLWLocks(void)
Definition: lwlock.c:468
union LWLockMinimallyPadded LWLockMinimallyPadded
unsigned int uint32
Definition: c.h:374
uint16 tranche
Definition: lwlock.h:33
PGDLLIMPORT NamedLWLockTranche * NamedLWLockTrancheArray
Definition: lwlock.c:239
bool LWLockAcquire(LWLock *lock, LWLockMode mode)
Definition: lwlock.c:1208
char * trancheName
Definition: lwlock.h:95
void LWLockRegisterTranche(int tranche_id, const char *tranche_name)
Definition: lwlock.c:653
LWLock lock
Definition: lwlock.h:78
size_t Size
Definition: c.h:473
#define newval
BuiltinTrancheIds
Definition: lwlock.h:194
PGDLLIMPORT LWLockPadded * MainLWLockArray
Definition: lwlock.c:200
void RequestNamedLWLockTranche(const char *tranche_name, int num_lwlocks)
Definition: lwlock.c:705
bool LWLockWaitForVar(LWLock *lock, uint64 *valptr, uint64 oldval, uint64 *newval)
Definition: lwlock.c:1619
#define LWLOCK_PADDED_SIZE
Definition: lwlock.h:72
void LWLockRelease(LWLock *lock)
Definition: lwlock.c:1812
Definition: proc.h:112
LWLockPadded * GetNamedLWLockTranche(const char *tranche_name)
Definition: lwlock.c:599
long val
Definition: informix.c:664
struct LWLock LWLock
union LWLockPadded LWLockPadded
PGDLLIMPORT int NamedLWLockTrancheRequests
Definition: lwlock.c:236