xtc_lwlock.h

/*-
 * Copyright (c) 2026, The XTC Project
 * @stability stable
 * Use of this source code is governed by the ISC License,
 * a copy of which is in the file LICENSE in the top-level directory
 * of this distribution.
 *
 * src/inc/xtc_lwlock.h
 *      Lightweight lock -- multi-reader / single-writer lock with an
 *      atomic state word and an explicit wait queue.  Ported from
 *      postgres/lrlck/src/backend/storage/lmgr/lwlock.c, retaining the
 *      state-encoding scheme verbatim:
 *
 *        bit 31:  LW_FLAG_HAS_WAITERS        -- wakeups are pending
 *        bit 30:  LW_FLAG_WAKE_IN_PROGRESS   -- another thread is waking
 *        bit 29:  LW_FLAG_QUEUE_LOCKED       -- wait-queue spinlock
 *        bits 0..N-1: shared-holder count
 *        bit N:   LW_VAL_EXCLUSIVE           -- exclusive owner present
 *
 *      N is configurable via XTC_LWLOCK_MAX_BACKENDS (default 4096).
 *
 *      Trade-offs vs xtc_rwlock:
 *        + Single-CAS fast path for both acquire and release.
 *        + No fairness guarantees beyond FIFO wakeup order.
 *        + Cache-line-aligned struct (avoid false sharing).
 *        - Caller must release in reverse order of acquire.
 *        - No timeout/cancellable acquire (use xtc_amutex/xtc_rwlock for
 *          those scenarios).
 *
 *      Trade-offs vs xtc_lrlock:
 *        + Multiple writers (serialized).
 *        + No second copy of the data.
 *        + Reads aren't wait-free \u2014 they CAS the state word.
 *        - Bigger contention surface; pick lrlock for read-mostly.
 */
 
#ifndef XTC_LWLOCK_H
#define XTC_LWLOCK_H
 
#include "xtc_export.h"
 
#include <pthread.h>
#include <stdatomic.h>
#include <stdint.h>
 
#include "xtc.h"
 
#ifndef XTC_LWLOCK_MAX_BACKENDS
#define XTC_LWLOCK_MAX_BACKENDS 4096   /* power of 2; bits 0..11 = shared count */
#endif
 
typedef enum xtc_lwlock_mode {
        XTC_LW_EXCLUSIVE = 0,
        XTC_LW_SHARED    = 1
} xtc_lwlock_mode_t;
 
/* The lock itself.  Caller embeds in any structure or stack-allocates. */
typedef struct xtc_lwlock {
        _Atomic uint32_t  state;
        pthread_mutex_t   wait_mu;
        pthread_cond_t    wait_cv;
        int               n_waiters;     /* protected by wait_mu */
        int               wakers_pending;/* protected by wait_mu */
        uint16_t          tranche;       /* user-tag; for diagnostics only */
        uint8_t           initialised;
        uint8_t           pad_;
        /* DST fiber-park wait queue (protected by wait_mu).  Only touched
         * when a caller acquires from inside a fiber under the sim
         * scheduler; the production OS-thread path uses wait_cv and never
         * reads/writes these.  Opaque here -- struct fiber_waiter lives in
         * lock_lw.c. */
        void             *wq_head;
        void             *wq_tail;
} xtc_lwlock_t;
 
/*
 * PUBLIC: int  xtc_lwlock_init __P((xtc_lwlock_t *, uint16_t));
 * PUBLIC: void xtc_lwlock_destroy __P((xtc_lwlock_t *));
 *
 * PUBLIC: int  xtc_lwlock_acquire __P((xtc_lwlock_t *, xtc_lwlock_mode_t));
 * PUBLIC: int  xtc_lwlock_acquire_cond __P((xtc_lwlock_t *, xtc_lwlock_mode_t));
 * PUBLIC: void xtc_lwlock_release __P((xtc_lwlock_t *));
 *
 * PUBLIC: int  xtc_lwlock_held_by_me __P((const xtc_lwlock_t *));
 * PUBLIC: int  xtc_lwlock_held_by_me_in_mode __P((const xtc_lwlock_t *, xtc_lwlock_mode_t));
 *
 * PUBLIC: void xtc_lwlock_track_enable __P((int));
 * PUBLIC: long xtc_lwlock_track_violations __P((void));
 * PUBLIC: void xtc_lwlock_track_reset __P((void));
 * PUBLIC: void xtc_lwlock_track_set_handler __P((xtc_lwlock_track_fn, void *));
 */
 
XTC_API int   xtc_lwlock_init(xtc_lwlock_t *lock, uint16_t tranche);
XTC_API void  xtc_lwlock_destroy(xtc_lwlock_t *lock);
 
/* Acquire blocks until the lock is held in `mode`.  Returns XTC_OK. */
XTC_API int   xtc_lwlock_acquire(xtc_lwlock_t *lock, xtc_lwlock_mode_t mode);
 
/* Conditional acquire -- non-blocking.  Returns XTC_OK on success,
 * XTC_E_AGAIN if the lock would block. */
XTC_API int   xtc_lwlock_acquire_cond(xtc_lwlock_t *lock, xtc_lwlock_mode_t mode);
 
/* Release the lock.  Mode is recorded in the per-thread held-list,
 * so the caller doesn't have to pass it back. */
XTC_API void  xtc_lwlock_release(xtc_lwlock_t *lock);
 
/* Diagnostics. */
XTC_API int   xtc_lwlock_held_by_me(const xtc_lwlock_t *lock);
XTC_API int   xtc_lwlock_held_by_me_in_mode(const xtc_lwlock_t *lock,
                                            xtc_lwlock_mode_t mode);
 
/*
 * Optional lock-order (WITNESS) tracker.  Off by default; enable in
 * test/staging to catch lock-order inversions among lwlocks (the
 * deadlock precursor the lwlock primitive cannot detect on its own,
 * unlike xtc_lockmgr).  Edges are keyed by tranche (the lock class):
 * the handler, if set, fires with (held_tranche, acquired_tranche)
 * each time an acquisition reverses a previously-seen order.
 * xtc_lwlock_track_violations counts those; xtc_lwlock_track_reset
 * clears the edge set + counter.
 */
typedef void (*xtc_lwlock_track_fn)(uint16_t held_tranche,
                                    uint16_t acquired_tranche, void *user);
XTC_API void  xtc_lwlock_track_enable(int on);
XTC_API long  xtc_lwlock_track_violations(void);
XTC_API void  xtc_lwlock_track_reset(void);
XTC_API void  xtc_lwlock_track_set_handler(xtc_lwlock_track_fn fn, void *user);
 
#endif /* XTC_LWLOCK_H */