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 "lib/ilist.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; 50 Size array_stride; 51 } LWLockTranche; 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 dlist_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 { 104 LWLock lock; 105 char pad[LWLOCK_PADDED_SIZE]; 106 } LWLockPadded; 107 108 /* LWLock, minimally padded */ 109 typedef union LWLockMinimallyPadded 110 { 111 LWLock lock; 112 char pad[LWLOCK_MINIMAL_SIZE]; 113 } LWLockMinimallyPadded; 114 115 extern PGDLLIMPORT LWLockPadded *MainLWLockArray; 116 extern char *MainLWLockNames[]; 117 118 /* struct for storing named tranche information */ 119 typedef struct NamedLWLockTranche 120 { 121 LWLockTranche lwLockTranche; 122 int trancheId; 123 } NamedLWLockTranche; 124 125 extern PGDLLIMPORT NamedLWLockTranche *NamedLWLockTrancheArray; 126 extern PGDLLIMPORT int NamedLWLockTrancheRequests; 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 { 159 LW_EXCLUSIVE, 160 LW_SHARED, 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 179 extern bool LWLockWaitForVar(LWLock *lock, uint64 *valptr, uint64 oldval, uint64 *newval); 180 extern void LWLockUpdateVar(LWLock *lock, uint64 *valptr, uint64 value); 181 182 extern Size LWLockShmemSize(void); 183 extern void CreateLWLocks(void); 184 extern void InitLWLockAccess(void); 185 186 extern const char *GetLWLockIdentifier(uint8 classId, uint16 eventId); 187 188 /* 189 * Extensions (or core code) can obtain an LWLocks by calling 190 * RequestNamedLWLockTranche() during postmaster startup. Subsequently, 191 * call GetNamedLWLockTranche() to obtain a pointer to an array containing 192 * the number of LWLocks requested. 193 */ 194 extern void RequestNamedLWLockTranche(const char *tranche_name, int num_lwlocks); 195 extern LWLockPadded *GetNamedLWLockTranche(const char *tranche_name); 196 197 /* 198 * There is another, more flexible method of obtaining lwlocks. First, call 199 * LWLockNewTrancheId just once to obtain a tranche ID; this allocates from 200 * a shared counter. Next, each individual process using the tranche should 201 * call LWLockRegisterTranche() to associate that tranche ID with appropriate 202 * metadata. Finally, LWLockInitialize should be called just once per lwlock, 203 * passing the tranche ID as an argument. 204 * 205 * It may seem strange that each process using the tranche must register it 206 * separately, but dynamic shared memory segments aren't guaranteed to be 207 * mapped at the same address in all coordinating backends, so storing the 208 * registration in the main shared memory segment wouldn't work for that case. 209 */ 210 extern int LWLockNewTrancheId(void); 211 extern void LWLockRegisterTranche(int tranche_id, LWLockTranche *tranche); 212 extern void LWLockInitialize(LWLock *lock, int tranche_id); 213 214 /* 215 * We reserve a few predefined tranche IDs. A call to LWLockNewTrancheId 216 * will never return a value less than LWTRANCHE_FIRST_USER_DEFINED. 217 */ 218 typedef enum BuiltinTrancheIds 219 { 220 LWTRANCHE_MAIN, 221 LWTRANCHE_CLOG_BUFFERS, 222 LWTRANCHE_COMMITTS_BUFFERS, 223 LWTRANCHE_SUBTRANS_BUFFERS, 224 LWTRANCHE_MXACTOFFSET_BUFFERS, 225 LWTRANCHE_MXACTMEMBER_BUFFERS, 226 LWTRANCHE_ASYNC_BUFFERS, 227 LWTRANCHE_OLDSERXID_BUFFERS, 228 LWTRANCHE_WAL_INSERT, 229 LWTRANCHE_BUFFER_CONTENT, 230 LWTRANCHE_BUFFER_IO_IN_PROGRESS, 231 LWTRANCHE_REPLICATION_ORIGIN, 232 LWTRANCHE_REPLICATION_SLOT_IO_IN_PROGRESS, 233 LWTRANCHE_PROC, 234 LWTRANCHE_BUFFER_MAPPING, 235 LWTRANCHE_LOCK_MANAGER, 236 LWTRANCHE_PREDICATE_LOCK_MANAGER, 237 LWTRANCHE_FIRST_USER_DEFINED 238 } BuiltinTrancheIds; 239 240 /* 241 * Prior to PostgreSQL 9.4, we used an enum type called LWLockId to refer 242 * to LWLocks. New code should instead use LWLock *. However, for the 243 * convenience of third-party code, we include the following typedef. 244 */ 245 typedef LWLock *LWLockId; 246 247 #endif /* LWLOCK_H */ 248