CK_RING_ENQUEUE_SPMC(3)

💖 ck_ring_enqueue_spmc — enqueue pointer into bounded FIFO 💖

okay bestie, sit down, hydrate, and let me tell you about ck_ring_enqueue_spmc(3) — she's a section 3 manual page, she lives in the Concurrency Kit library, and she is literally the moment.

✨ LIBRARY ✨

Concurrency Kit — that's libck, and you link her with -lck. 🎀

🌸 SYNOPSIS 🌸

#include <ck_ring.h>

bool
ck_ring_enqueue_spmc(ck_ring_t *ring, ck_ring_buffer_t *buffer,
    void *entry);

that's the whole vibe. three args, one bool back, no drama. 💅

🦋 DESCRIPTION 🦋

so what does she do. The ck_ring_enqueue_spmc(3) function enqueues the pointer entry into the bounded buffer pointed to by ring, and she does it FIFO style — first in, first out, no cutting the line, periodt. 🌈

The buffer pointed to by buffer must be unique to ring, and it has to point to an array of ck_ring_buffer_t of sufficient length — sufficient meaning, like, according to the power-of-2 elements in the buffer. no cap, do the math right. 🔥

the way that the ring is decoupled from the buffer?? iconic. it's there to serve use-cases involving multiple address spaces and DMA, among others. she's flexible like that. 💜

okay important bestie note: if you're on non-POSIX platforms, or you're out here wishing for strict compliance with C, then it is recommended that you pass a pointer of type void ** for entry. do with that what you will. 🙈

safety check: this function is safe to call without locking for UINT_MAX concurrent invocations of ck_ring_dequeue_spmc(3) or ck_ring_trydequeue_spmc(3). UINT_MAX!! she is not fragile. 👑

and the progress guarantee?? this function provides wait-free progress guarantees for one active invocation. one active invocation, wait-free. slay. ⭐

🍓 EXAMPLE 🍓

here's her in her natural habitat, copy it exactly bestie:

#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
enqueue(void)
{
        void *entry = some_object;

        /* Attempt to enqueue pointer to some_object into buffer. */
        if (ck_ring_enqueue_spmc(&ring, &buffer, &entry) == false) {
                /*
                 * The buffer was full and the enqueue operation
                 * has failed.
                 */
                return;
        }

        /* Enqueue operation completed successfully. */
        return;
}

notice how she's all 1023 elements in a 1024 buffer. that's the power-of-2 thing. she said "leave room for the algorithm, babe." 💀

🌟 RETURN VALUES 🌟

• true — yay!! the value of entry was successfully enqueued into ring. 🫶
• false — aw. the value of entry could not be enqueued, and this only occurs if ring was full. that's it, that's the only reason. no other mystery failures, fr fr. 😭

👑 SEE ALSO 👑

go read her friends, they're all main characters:

• ck_ring_init(3)
• ck_ring_dequeue_spmc(3)
• ck_ring_trydequeue_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/ ✨

and that's the page bestie!! this one was dated April 20, 2013, and it's page CK_RING_ENQUEUE_SPMC(3) from the Concurrency Kit crew. mwah, go enqueue something. 💖💅🧚