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-2024, 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 /* what state of the wait process is a backend in */
27 typedef enum LWLockWaitState
28 {
29  LW_WS_NOT_WAITING, /* not currently waiting / woken up */
30  LW_WS_WAITING, /* currently waiting */
31  LW_WS_PENDING_WAKEUP, /* removed from waitlist, but not yet
32  * signalled */
34 
35 /*
36  * Code outside of lwlock.c should not manipulate the contents of this
37  * structure directly, but we have to declare it here to allow LWLocks to be
38  * incorporated into other data structures.
39  */
40 typedef struct LWLock
41 {
42  uint16 tranche; /* tranche ID */
43  pg_atomic_uint32 state; /* state of exclusive/nonexclusive lockers */
44  proclist_head waiters; /* list of waiting PGPROCs */
45 #ifdef LOCK_DEBUG
46  pg_atomic_uint32 nwaiters; /* number of waiters */
47  struct PGPROC *owner; /* last exclusive owner of the lock */
48 #endif
50 
51 /*
52  * In most cases, it's desirable to force each tranche of LWLocks to be aligned
53  * on a cache line boundary and make the array stride a power of 2. This saves
54  * a few cycles in indexing, but more importantly ensures that individual
55  * LWLocks don't cross cache line boundaries. This reduces cache contention
56  * problems, especially on AMD Opterons. In some cases, it's useful to add
57  * even more padding so that each LWLock takes up an entire cache line; this is
58  * useful, for example, in the main LWLock array, where the overall number of
59  * locks is small but some are heavily contended.
60  */
61 #define LWLOCK_PADDED_SIZE PG_CACHE_LINE_SIZE
62 
64  "Miscalculated LWLock padding");
65 
66 /* LWLock, padded to a full cache line size */
67 typedef union LWLockPadded
68 {
72 
74 
75 /* struct for storing named tranche information */
76 typedef struct NamedLWLockTranche
77 {
78  int trancheId;
79  char *trancheName;
81 
84 
85 /* Names for fixed lwlocks */
86 #include "storage/lwlocknames.h"
87 
88 /*
89  * It's a bit odd to declare NUM_BUFFER_PARTITIONS and NUM_LOCK_PARTITIONS
90  * here, but we need them to figure out offsets within MainLWLockArray, and
91  * having this file include lock.h or bufmgr.h would be backwards.
92  */
93 
94 /* Number of partitions of the shared buffer mapping hashtable */
95 #define NUM_BUFFER_PARTITIONS 128
96 
97 /* Number of partitions the shared lock tables are divided into */
98 #define LOG2_NUM_LOCK_PARTITIONS 4
99 #define NUM_LOCK_PARTITIONS (1 << LOG2_NUM_LOCK_PARTITIONS)
100 
101 /* Number of partitions the shared predicate lock tables are divided into */
102 #define LOG2_NUM_PREDICATELOCK_PARTITIONS 4
103 #define NUM_PREDICATELOCK_PARTITIONS (1 << LOG2_NUM_PREDICATELOCK_PARTITIONS)
104 
105 /* Offsets for various chunks of preallocated lwlocks. */
106 #define BUFFER_MAPPING_LWLOCK_OFFSET NUM_INDIVIDUAL_LWLOCKS
107 #define LOCK_MANAGER_LWLOCK_OFFSET \
108  (BUFFER_MAPPING_LWLOCK_OFFSET + NUM_BUFFER_PARTITIONS)
109 #define PREDICATELOCK_MANAGER_LWLOCK_OFFSET \
110  (LOCK_MANAGER_LWLOCK_OFFSET + NUM_LOCK_PARTITIONS)
111 #define NUM_FIXED_LWLOCKS \
112  (PREDICATELOCK_MANAGER_LWLOCK_OFFSET + NUM_PREDICATELOCK_PARTITIONS)
113 
114 typedef enum LWLockMode
115 {
118  LW_WAIT_UNTIL_FREE, /* A special mode used in PGPROC->lwWaitMode,
119  * when waiting for lock to become free. Not
120  * to be used as LWLockAcquire argument */
122 
123 
124 #ifdef LOCK_DEBUG
125 extern PGDLLIMPORT bool Trace_lwlocks;
126 #endif
127 
128 extern bool LWLockAcquire(LWLock *lock, LWLockMode mode);
129 extern bool LWLockConditionalAcquire(LWLock *lock, LWLockMode mode);
130 extern bool LWLockAcquireOrWait(LWLock *lock, LWLockMode mode);
131 extern void LWLockRelease(LWLock *lock);
132 extern void LWLockReleaseClearVar(LWLock *lock, pg_atomic_uint64 *valptr, uint64 val);
133 extern void LWLockReleaseAll(void);
134 extern bool LWLockHeldByMe(LWLock *lock);
135 extern bool LWLockAnyHeldByMe(LWLock *lock, int nlocks, size_t stride);
136 extern bool LWLockHeldByMeInMode(LWLock *lock, LWLockMode mode);
137 
138 extern bool LWLockWaitForVar(LWLock *lock, pg_atomic_uint64 *valptr, uint64 oldval, uint64 *newval);
139 extern void LWLockUpdateVar(LWLock *lock, pg_atomic_uint64 *valptr, uint64 val);
140 
141 extern Size LWLockShmemSize(void);
142 extern void CreateLWLocks(void);
143 extern void InitLWLockAccess(void);
144 
145 extern const char *GetLWLockIdentifier(uint32 classId, uint16 eventId);
146 
147 /*
148  * Extensions (or core code) can obtain an LWLocks by calling
149  * RequestNamedLWLockTranche() during postmaster startup. Subsequently,
150  * call GetNamedLWLockTranche() to obtain a pointer to an array containing
151  * the number of LWLocks requested.
152  */
153 extern void RequestNamedLWLockTranche(const char *tranche_name, int num_lwlocks);
154 extern LWLockPadded *GetNamedLWLockTranche(const char *tranche_name);
155 
156 /*
157  * There is another, more flexible method of obtaining lwlocks. First, call
158  * LWLockNewTrancheId just once to obtain a tranche ID; this allocates from
159  * a shared counter. Next, each individual process using the tranche should
160  * call LWLockRegisterTranche() to associate that tranche ID with a name.
161  * Finally, LWLockInitialize should be called just once per lwlock, passing
162  * the tranche ID as an argument.
163  *
164  * It may seem strange that each process using the tranche must register it
165  * separately, but dynamic shared memory segments aren't guaranteed to be
166  * mapped at the same address in all coordinating backends, so storing the
167  * registration in the main shared memory segment wouldn't work for that case.
168  */
169 extern int LWLockNewTrancheId(void);
170 extern void LWLockRegisterTranche(int tranche_id, const char *tranche_name);
171 extern void LWLockInitialize(LWLock *lock, int tranche_id);
172 
173 /*
174  * Every tranche ID less than NUM_INDIVIDUAL_LWLOCKS is reserved; also,
175  * we reserve additional tranche IDs for builtin tranches not included in
176  * the set of individual LWLocks. A call to LWLockNewTrancheId will never
177  * return a value less than LWTRANCHE_FIRST_USER_DEFINED.
178  */
179 typedef enum BuiltinTrancheIds
180 {
181  LWTRANCHE_XACT_BUFFER = NUM_INDIVIDUAL_LWLOCKS,
221 
222 /*
223  * Prior to PostgreSQL 9.4, we used an enum type called LWLockId to refer
224  * to LWLocks. New code should instead use LWLock *. However, for the
225  * convenience of third-party code, we include the following typedef.
226  */
227 typedef LWLock *LWLockId;
228 
229 #endif /* LWLOCK_H */
unsigned short uint16
Definition: c.h:492
unsigned int uint32
Definition: c.h:493
#define PGDLLIMPORT
Definition: c.h:1303
size_t Size
Definition: c.h:592
#define newval
long val
Definition: informix.c:664
void LWLockUpdateVar(LWLock *lock, pg_atomic_uint64 *valptr, uint64 val)
Definition: lwlock.c:1724
union LWLockPadded LWLockPadded
bool LWLockHeldByMe(LWLock *lock)
Definition: lwlock.c:1897
const char * GetLWLockIdentifier(uint32 classId, uint16 eventId)
Definition: lwlock.c:771
LWLockPadded * GetNamedLWLockTranche(const char *tranche_name)
Definition: lwlock.c:574
void LWLockReleaseClearVar(LWLock *lock, pg_atomic_uint64 *valptr, uint64 val)
Definition: lwlock.c:1858
bool LWLockAcquire(LWLock *lock, LWLockMode mode)
Definition: lwlock.c:1172
void CreateLWLocks(void)
Definition: lwlock.c:451
LWLockWaitState
Definition: lwlock.h:28
@ LW_WS_NOT_WAITING
Definition: lwlock.h:29
@ LW_WS_WAITING
Definition: lwlock.h:30
@ LW_WS_PENDING_WAKEUP
Definition: lwlock.h:31
PGDLLIMPORT NamedLWLockTranche * NamedLWLockTrancheArray
Definition: lwlock.c:228
struct NamedLWLockTranche NamedLWLockTranche
#define LWLOCK_PADDED_SIZE
Definition: lwlock.h:61
void LWLockRegisterTranche(int tranche_id, const char *tranche_name)
Definition: lwlock.c:628
bool LWLockHeldByMeInMode(LWLock *lock, LWLockMode mode)
Definition: lwlock.c:1941
PGDLLIMPORT int NamedLWLockTrancheRequests
Definition: lwlock.c:225
bool LWLockWaitForVar(LWLock *lock, pg_atomic_uint64 *valptr, uint64 oldval, uint64 *newval)
Definition: lwlock.c:1588
int LWLockNewTrancheId(void)
Definition: lwlock.c:604
void RequestNamedLWLockTranche(const char *tranche_name, int num_lwlocks)
Definition: lwlock.c:670
void LWLockRelease(LWLock *lock)
Definition: lwlock.c:1785
BuiltinTrancheIds
Definition: lwlock.h:180
@ LWTRANCHE_FIRST_USER_DEFINED
Definition: lwlock.h:219
@ LWTRANCHE_SHARED_TIDBITMAP
Definition: lwlock.h:202
@ LWTRANCHE_SERIAL_SLRU
Definition: lwlock.h:216
@ LWTRANCHE_PER_SESSION_DSA
Definition: lwlock.h:198
@ LWTRANCHE_PARALLEL_QUERY_DSA
Definition: lwlock.h:197
@ LWTRANCHE_COMMITTS_BUFFER
Definition: lwlock.h:182
@ LWTRANCHE_PGSTATS_HASH
Definition: lwlock.h:206
@ LWTRANCHE_SUBTRANS_BUFFER
Definition: lwlock.h:183
@ LWTRANCHE_PER_SESSION_RECORD_TYPMOD
Definition: lwlock.h:200
@ LWTRANCHE_LAUNCHER_HASH
Definition: lwlock.h:209
@ LWTRANCHE_DSM_REGISTRY_DSA
Definition: lwlock.h:210
@ LWTRANCHE_XACT_BUFFER
Definition: lwlock.h:181
@ LWTRANCHE_DSM_REGISTRY_HASH
Definition: lwlock.h:211
@ LWTRANCHE_NOTIFY_SLRU
Definition: lwlock.h:215
@ LWTRANCHE_REPLICATION_ORIGIN_STATE
Definition: lwlock.h:190
@ LWTRANCHE_MULTIXACTOFFSET_SLRU
Definition: lwlock.h:214
@ LWTRANCHE_PARALLEL_APPEND
Definition: lwlock.h:203
@ LWTRANCHE_REPLICATION_SLOT_IO
Definition: lwlock.h:191
@ LWTRANCHE_SUBTRANS_SLRU
Definition: lwlock.h:217
@ LWTRANCHE_MULTIXACTMEMBER_SLRU
Definition: lwlock.h:213
@ LWTRANCHE_BUFFER_CONTENT
Definition: lwlock.h:189
@ LWTRANCHE_MULTIXACTMEMBER_BUFFER
Definition: lwlock.h:185
@ LWTRANCHE_NOTIFY_BUFFER
Definition: lwlock.h:186
@ LWTRANCHE_PER_SESSION_RECORD_TYPE
Definition: lwlock.h:199
@ LWTRANCHE_PREDICATE_LOCK_MANAGER
Definition: lwlock.h:195
@ LWTRANCHE_BUFFER_MAPPING
Definition: lwlock.h:193
@ LWTRANCHE_SERIAL_BUFFER
Definition: lwlock.h:187
@ LWTRANCHE_LAUNCHER_DSA
Definition: lwlock.h:208
@ LWTRANCHE_PGSTATS_DSA
Definition: lwlock.h:205
@ LWTRANCHE_PARALLEL_HASH_JOIN
Definition: lwlock.h:196
@ LWTRANCHE_COMMITTS_SLRU
Definition: lwlock.h:212
@ LWTRANCHE_PGSTATS_DATA
Definition: lwlock.h:207
@ LWTRANCHE_PER_XACT_PREDICATE_LIST
Definition: lwlock.h:204
@ LWTRANCHE_XACT_SLRU
Definition: lwlock.h:218
@ LWTRANCHE_MULTIXACTOFFSET_BUFFER
Definition: lwlock.h:184
@ LWTRANCHE_WAL_INSERT
Definition: lwlock.h:188
@ LWTRANCHE_LOCK_MANAGER
Definition: lwlock.h:194
@ LWTRANCHE_SHARED_TUPLESTORE
Definition: lwlock.h:201
@ LWTRANCHE_LOCK_FASTPATH
Definition: lwlock.h:192
void LWLockReleaseAll(void)
Definition: lwlock.c:1880
void LWLockInitialize(LWLock *lock, int tranche_id)
Definition: lwlock.c:707
bool LWLockConditionalAcquire(LWLock *lock, LWLockMode mode)
Definition: lwlock.c:1343
bool LWLockAcquireOrWait(LWLock *lock, LWLockMode mode)
Definition: lwlock.c:1400
LWLockMode
Definition: lwlock.h:115
@ LW_SHARED
Definition: lwlock.h:117
@ LW_WAIT_UNTIL_FREE
Definition: lwlock.h:118
@ LW_EXCLUSIVE
Definition: lwlock.h:116
PGDLLIMPORT LWLockPadded * MainLWLockArray
Definition: lwlock.c:189
StaticAssertDecl(sizeof(LWLock)<=LWLOCK_PADDED_SIZE, "Miscalculated LWLock padding")
LWLock * LWLockId
Definition: lwlock.h:227
struct LWLock LWLock
Size LWLockShmemSize(void)
Definition: lwlock.c:421
bool LWLockAnyHeldByMe(LWLock *lock, int nlocks, size_t stride)
Definition: lwlock.c:1915
void InitLWLockAccess(void)
Definition: lwlock.c:558
static PgChecksumMode mode
Definition: pg_checksums.c:56
Definition: lwlock.h:41
pg_atomic_uint32 state
Definition: lwlock.h:43
uint16 tranche
Definition: lwlock.h:42
proclist_head waiters
Definition: lwlock.h:44
char * trancheName
Definition: lwlock.h:79
Definition: proc.h:157
LWLock lock
Definition: lwlock.h:69
char pad[LWLOCK_PADDED_SIZE]
Definition: lwlock.h:70