lwlock.h

Go to the documentation of this file.

/*-------------------------------------------------------------------------
 *
 * lwlock.h
 *    Lightweight lock manager
 *
 *
 * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
 * Portions Copyright (c) 1994, Regents of the University of California
 *
 * src/include/storage/lwlock.h
 *
 *-------------------------------------------------------------------------
 */
#ifndef LWLOCK_H
#define LWLOCK_H
 
#ifdef FRONTEND
#error "lwlock.h may not be included from frontend code"
#endif
 
#include "port/atomics.h"
#include "storage/lwlocknames.h"
#include "storage/proclist_types.h"
 
struct PGPROC;
 
/* what state of the wait process is a backend in */
typedef enum LWLockWaitState
{
    LW_WS_NOT_WAITING,          /* not currently waiting / woken up */
    LW_WS_WAITING,              /* currently waiting */
    LW_WS_PENDING_WAKEUP,       /* removed from waitlist, but not yet
                                 * signalled */
}           LWLockWaitState;
 
/*
 * Code outside of lwlock.c should not manipulate the contents of this
 * structure directly, but we have to declare it here to allow LWLocks to be
 * incorporated into other data structures.
 */
typedef struct LWLock
{
    uint16      tranche;        /* tranche ID */
    pg_atomic_uint32 state;     /* state of exclusive/nonexclusive lockers */
    proclist_head waiters;      /* list of waiting PGPROCs */
#ifdef LOCK_DEBUG
    pg_atomic_uint32 nwaiters;  /* number of waiters */
    struct PGPROC *owner;       /* last exclusive owner of the lock */
#endif
} LWLock;
 
/*
 * In most cases, it's desirable to force each tranche of LWLocks to be aligned
 * on a cache line boundary and make the array stride a power of 2.  This saves
 * a few cycles in indexing, but more importantly ensures that individual
 * LWLocks don't cross cache line boundaries.  This reduces cache contention
 * problems, especially on AMD Opterons.  In some cases, it's useful to add
 * even more padding so that each LWLock takes up an entire cache line; this is
 * useful, for example, in the main LWLock array, where the overall number of
 * locks is small but some are heavily contended.
 */
#define LWLOCK_PADDED_SIZE  PG_CACHE_LINE_SIZE
 
StaticAssertDecl(sizeof(LWLock) <= LWLOCK_PADDED_SIZE,
                 "Miscalculated LWLock padding");
 
/* LWLock, padded to a full cache line size */
typedef union LWLockPadded
{
    LWLock      lock;
    char        pad[LWLOCK_PADDED_SIZE];
} LWLockPadded;
 
extern PGDLLIMPORT LWLockPadded *MainLWLockArray;
 
/* forward declaration of private type for use only by lwlock.c */
typedef struct NamedLWLockTrancheRequest NamedLWLockTrancheRequest;
 
extern PGDLLIMPORT char **LWLockTrancheNames;
extern PGDLLIMPORT int NamedLWLockTrancheRequests;
extern PGDLLIMPORT NamedLWLockTrancheRequest *NamedLWLockTrancheRequestArray;
extern PGDLLIMPORT int *LWLockCounter;
 
/*
 * It's a bit odd to declare NUM_BUFFER_PARTITIONS and NUM_LOCK_PARTITIONS
 * here, but we need them to figure out offsets within MainLWLockArray, and
 * having this file include lock.h or bufmgr.h would be backwards.
 */
 
/* Number of partitions of the shared buffer mapping hashtable */
#define NUM_BUFFER_PARTITIONS  128
 
/* Number of partitions the shared lock tables are divided into */
#define LOG2_NUM_LOCK_PARTITIONS  4
#define NUM_LOCK_PARTITIONS  (1 << LOG2_NUM_LOCK_PARTITIONS)
 
/* Number of partitions the shared predicate lock tables are divided into */
#define LOG2_NUM_PREDICATELOCK_PARTITIONS  4
#define NUM_PREDICATELOCK_PARTITIONS  (1 << LOG2_NUM_PREDICATELOCK_PARTITIONS)
 
/* Offsets for various chunks of preallocated lwlocks. */
#define BUFFER_MAPPING_LWLOCK_OFFSET    NUM_INDIVIDUAL_LWLOCKS
#define LOCK_MANAGER_LWLOCK_OFFSET      \
    (BUFFER_MAPPING_LWLOCK_OFFSET + NUM_BUFFER_PARTITIONS)
#define PREDICATELOCK_MANAGER_LWLOCK_OFFSET \
    (LOCK_MANAGER_LWLOCK_OFFSET + NUM_LOCK_PARTITIONS)
#define NUM_FIXED_LWLOCKS \
    (PREDICATELOCK_MANAGER_LWLOCK_OFFSET + NUM_PREDICATELOCK_PARTITIONS)
 
typedef enum LWLockMode
{
    LW_EXCLUSIVE,
    LW_SHARED,
    LW_WAIT_UNTIL_FREE,         /* A special mode used in PGPROC->lwWaitMode,
                                 * when waiting for lock to become free. Not
                                 * to be used as LWLockAcquire argument */
} LWLockMode;
 
 
#ifdef LOCK_DEBUG
extern PGDLLIMPORT bool Trace_lwlocks;
#endif
 
extern bool LWLockAcquire(LWLock *lock, LWLockMode mode);
extern bool LWLockConditionalAcquire(LWLock *lock, LWLockMode mode);
extern bool LWLockAcquireOrWait(LWLock *lock, LWLockMode mode);
extern void LWLockRelease(LWLock *lock);
extern void LWLockReleaseClearVar(LWLock *lock, pg_atomic_uint64 *valptr, uint64 val);
extern void LWLockReleaseAll(void);
extern void LWLockDisown(LWLock *lock);
extern void LWLockReleaseDisowned(LWLock *lock, LWLockMode mode);
extern void ForEachLWLockHeldByMe(void (*callback) (LWLock *, LWLockMode, void *),
                                  void *context);
extern bool LWLockHeldByMe(LWLock *lock);
extern bool LWLockAnyHeldByMe(LWLock *lock, int nlocks, size_t stride);
extern bool LWLockHeldByMeInMode(LWLock *lock, LWLockMode mode);
 
extern bool LWLockWaitForVar(LWLock *lock, pg_atomic_uint64 *valptr, uint64 oldval, uint64 *newval);
extern void LWLockUpdateVar(LWLock *lock, pg_atomic_uint64 *valptr, uint64 val);
 
extern Size LWLockShmemSize(void);
extern void CreateLWLocks(void);
extern void InitLWLockAccess(void);
 
extern const char *GetLWLockIdentifier(uint32 classId, uint16 eventId);
 
/*
 * Extensions (or core code) can obtain an LWLocks by calling
 * RequestNamedLWLockTranche() during postmaster startup.  Subsequently,
 * call GetNamedLWLockTranche() to obtain a pointer to an array containing
 * the number of LWLocks requested.
 */
extern void RequestNamedLWLockTranche(const char *tranche_name, int num_lwlocks);
extern LWLockPadded *GetNamedLWLockTranche(const char *tranche_name);
 
/*
 * There is another, more flexible method of obtaining lwlocks. First, call
 * LWLockNewTrancheId to obtain a tranche ID; this allocates from a shared
 * counter.  Second, LWLockInitialize should be called just once per lwlock,
 * passing the tranche ID as an argument.
 */
extern int  LWLockNewTrancheId(const char *name);
extern void LWLockInitialize(LWLock *lock, int tranche_id);
 
/*
 * Every tranche ID less than NUM_INDIVIDUAL_LWLOCKS is reserved; also,
 * we reserve additional tranche IDs for builtin tranches not included in
 * the set of individual LWLocks.  A call to LWLockNewTrancheId will never
 * return a value less than LWTRANCHE_FIRST_USER_DEFINED.  The actual list of
 * built-in tranches is kept in lwlocklist.h.
 */
typedef enum BuiltinTrancheIds
{
    /*
     * LWTRANCHE_INVALID is an unused value that only exists to initialize the
     * rest of the tranches to appropriate values.
     */
    LWTRANCHE_INVALID = NUM_INDIVIDUAL_LWLOCKS - 1,
 
#define PG_LWLOCK(id, name)
#define PG_LWLOCKTRANCHE(id, name) LWTRANCHE_##id,
#include "storage/lwlocklist.h"
#undef PG_LWLOCK
#undef PG_LWLOCKTRANCHE
 
    LWTRANCHE_FIRST_USER_DEFINED,
}           BuiltinTrancheIds;
 
/*
 * Prior to PostgreSQL 9.4, we used an enum type called LWLockId to refer
 * to LWLocks.  New code should instead use LWLock *.  However, for the
 * convenience of third-party code, we include the following typedef.
 */
typedef LWLock *LWLockId;
 
#endif                          /* LWLOCK_H */