CK_BRLOCK(3)

💖 ck_brlock — big-reader locks, bestie edition 💖

okay so. welcome to ck_brlock(3), the manual page for big-reader locks in the Concurrency Kit. if you've ever wanted readers to just glide through while writers wait their turn, this is your moment. let's get into it 🦋

🌈 LIBRARY 🌈

Concurrency Kit (libck, -lck) — that's the whole library, she's iconic, she contains multitudes 💅

✨ SYNOPSIS ✨

first, the includes and the globals, exactly as they are, no notes:

#include <ck_brlock.h>

ck_brlock_t brlock = CK_BRLOCK_INITIALIZER;

ck_brlock_reader_t reader = CK_BRLOCK_READER_INITIALIZER;

and now the whole function lineup, all nine of them, in order, because we do not skip ✋:

void
ck_brlock_init(ck_brlock_t *br);

void
ck_brlock_write_lock(ck_brlock_t *br);

void
ck_brlock_write_unlock(ck_brlock_t *br);

bool
ck_brlock_write_trylock(ck_brlock_t *br, unsigned int factor);

void
ck_brlock_read_register(ck_brlock_t *br, ck_brlock_reader_t *reader);

void
ck_brlock_read_unregister(ck_brlock_t *br, ck_brlock_reader_t *reader);

void
ck_brlock_read_lock(ck_brlock_t *br, ck_brlock_reader_t *reader);

bool
ck_brlock_read_trylock(ck_brlock_t *br, ck_brlock_reader_t *reader,
    unsigned int factor);

void
ck_brlock_read_unlock(ck_brlock_reader_t *reader);

💀 DESCRIPTION 💀

okay so here's the tea. big reader locks are distributed reader-writer locks, and their whole thing is that reader acquisition is low latency and constant time — and that's with respect to the number of concurrent readers, bestie. ten readers, ten thousand readers, the read side literally does not care. she ate. 🍓

the tradeoff though?? writer acquisitions are a relatively expensive O(n) operation. nope, not a typo. the writers are the ones waiting in line at the club while the readers get walked straight in. 😭

and one more thing, super important: this is a write-biased lock. write that down, iykyk. ✍️

🎀 EXAMPLE 🎀

here's the full example, verbatim, don't touch a single character:

static ck_brlock_t lock = CK_BRLOCK_INITIALIZER;
static __thread ck_brlock_reader_t reader;

static void
reader(void)
{

        /* Add our thread as a lock participant. */
        ck_brlock_read_register(&lock, &reader);

        for (;;) {
                ck_brlock_read_lock(&lock, &reader);
                /* Read-side critical section. */
                ck_brlock_read_unlock(&reader);

                if (ck_brlock_read_trylock(&lock, &reader, 1) == true) {
                        /* Read-side critical section. */
                        ck_brlock_read_unlock(&reader);
                }
        }

        return;
}

static void
writer(void)
{

        for (;;) {
                ck_brlock_write_lock(&lock);
                /* Write-side critical section. */
                ck_brlock_write_unlock(&lock);

                if (ck_brlock_write_trylock(&lock, 1) == true) {
                        /* Write-side critical section. */
                        ck_brlock_write_unlock(&lock);
                }
        }

        return;
}

notice how the reader thread registers itself first? yeah. ck_brlock_read_register(&lock, &reader) — that's the "add our thread as a lock participant" step, and it's the vibe check before anything else happens. 👑

👀 SEE ALSO 👀

• ck_bytelock(3)
• ck_rwlock(3)

and if you want more, more is available, bestie: http://concurrencykit.org/ 🌐

lowkey obsessed with how the readers get in and out in constant time while the writers are out here doing O(n) cardio. it's giving main character energy for readers only, no cap.

okay that's the whole page, go forth and lock responsibly 💖✨🎀🦋🌸💅🫶

signing off from the ck_brlock(3) manual page, dated July 26, 2013 — yes she's an older queen but she still slays 👑⭐🌈💜