CK_RING_TRYDEQUEUE_SPMC(3)

💖 CK_RING_TRYDEQUEUE_SPMC 💖

okay bestie, welcome to ck_ring_trydequeue_spmc(3) — yes that's the whole manual name, say it three times fast, i dare you 🫶 it lives in the Concurrency Kit corner of the universe, aka libck, link it with -lck.

✨ NAME ✨

ck_ring_trydequeue_spmc — dequeue from a bounded FIFO, and it's allowed to just. fail. spuriously. no drama, that's the whole bit 💅

📚 LIBRARY 📚

Concurrency Kit (libck, -lck) — iconic, legendary, lowkey the moment.

🎀 SYNOPSIS 🎀

#include <ck_ring.h>

bool
ck_ring_trydequeue_spmc(ck_ring_t *ring, ck_ring_buffer_t *buffer,
    void *result);

🦋 DESCRIPTION 🦋

so. ck_ring_trydequeue_spmc(3) tries to dequeue one pointer from the bounded buffer that ring points at, and it does it FIFO style — first in, first out, oldest pointer first, no cutting the line 🙅‍♀️ that pointer lands in the pointer that result points at.

the buffer that buffer points at has to be unique to ring — no sharing, not even a little — and it must point to an array of ck_ring_buffer_t that's long enough (long enough meaning: according to the power-of-2 elements in the buffer, so do the math, bestie 🧮✨).

why is the ring decoupled from the buffer at all?? because use-cases like multiple address spaces and DMA (among others!!) needed it, and honestly? she ate. 💅

if you're on non-POSIX platforms or you simply want strict compliance with C, then the recommendation is to pass a pointer of type void ** for result. noted, respected, do it.

concurrency tea time ☕: this function is safe to call without locking for UINT_MAX concurrent ck_ring_dequeue_spmc(3) or ck_ring_trydequeue_spmc(3) invocations, plus up to one concurrent ck_ring_enqueue_spmc(3) or ck_ring_tryenqueue_spmc(3) invocation. that's it, that's the budget. one enqueuer, bestie, don't get greedy 🫶

this operation will always complete in a bounded number of steps. no infinite spirals, no waiting forever, we respect your time.

and now the part that makes people scream: it is possible for the function to return false even if ring is non-empty. yes. literally that. spurious failure is not a bug, it's a lifestyle. 😭

also the original manpage just ends that paragraph with the word "This" and nothing else 💀 not me getting left on read by a documentation file. we keep it, we honor it, we move on.

🌸 EXAMPLE 🌸

#include <ck_ring.h>

/* This ring was previously initialized with ck_ring_init. */
ck_ring_t ring;

/* The ring was initialized for 1023 elements. */
ck_ring_buffer_t buffer[1024];

void
dequeue(void)
{
        void *result;

        /* Dequeue from ring until contention is actively observed. */
        while (ck_ring_trydequeue_spmc(&ring, &buffer, &result) == true) {
                /*
                 * Results contains the oldest pointer in ring
                 * since the dequeue operation returned true.
                 */
                operation(result);
        }

        /* An empty ring was encountered, leave. */
        return;
}

look at that loop go 🔥 keep dequeuing until you actually observe contention, and the second it returns false, you leave. main character exit. 🚪✨

💀 RETURN VALUES 💀

• the function returns true if the dequeue operation completely successfully goes through in a bounded number of steps — and the result of the dequeue is stored in the value that result points to. slay. 👑
• otherwise the function returns false if the buffer was empty, or if the operation could not be completed in a bounded number of steps.

⚠️ if the function returns false, then the contents of result are undefined. do not read it. do not peek. do not look at it and hope. undefined is undefined, bestie, respect the boundary 🙈

🫶 SEE ALSO 🫶

• ck_ring_init(3)
• ck_ring_dequeue_spmc(3)
• ck_ring_enqueue_spmc(3)
• ck_ring_enqueue_spmc_size(3)
• ck_ring_dequeue_spsc(3)
• ck_ring_enqueue_spsc(3)
• ck_ring_enqueue_spsc_size(3)
• ck_ring_capacity(3)
• ck_ring_size(3)

additional information available at http://concurrencykit.org/ — go, read, obsess 🦋

and that's the whole page, babes 💖 this was CK_RING_TRYDEQUEUE_SPMC(3), dated April 20, 2013, and it's giving timeless. no cap. periodt. 🌈⭐💜