CK_RING_ENQUEUE_SPMC_SIZE(3)

💖 CK_RING_ENQUEUE_SPMC_SIZE — the manual, but make it cute 💖

okay bestie, welcome to the ck_ring_enqueue_spmc_size page from the Concurrency Kit manual. it lives in libck, and you link it with -lck. this is the one that yeets a pointer into a bounded FIFO and tells you how big the buffer got. main character behaviour fr fr 🌸

✨ NAME ✨

ck_ring_enqueue_spmc_size — enqueue pointer into bounded FIFO and return size of buffer 🎀

📚 LIBRARY 📚

Concurrency Kit (libck, -lck) 🫶

✨ SYNOPSIS ✨

#include <ck_ring.h>

bool
ck_ring_enqueue_spmc_size(ck_ring_t *ring, ck_ring_buffer_t *buffer,
    void *entry, unsigned int *length);

like. look at that signature. she's gorgeous. 💅

🌈 DESCRIPTION 🌈

so the ck_ring_enqueue_spmc(3) function enqueues the pointer entry into the bounded buffer that ring points at, FIFO style — first in, first out, no cutting the line, we're not animals 💀

now, the buffer that buffer points to has to be unique to ring, and it must point to an array of ck_ring_buffer_t of a sufficient length (based on the power-of-2 elements in the buffer). the whole reason the ring and the buffer are decoupled like that is to handle use-cases involving multiple address spaces and DMA, among others. iconic design choice, honestly. 🧚

lowkey important: if you're on non-POSIX platforms, or you just want strict compliance with C, it's recommended that you pass a pointer of type void ** for entry.

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). and it provides wait-free progress guarantees for one active invocation. no cap. 👑

🍓 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
enqueue(void)
{
        void *entry = some_object;
        unsigned int length;

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

        /*
         * If entry was the 101st or greater pointer in the buffer,
         * do something.
         */
        if (length > 100) {
                do_something;
        }

        return;
}

see how she eats? that's the whole vibe. 🫶

💜 RETURN VALUES 💜

• returns true if the value of entry was successfully enqueued into ring ✨
• returns false if the value of entry could not be enqueued — and that only happens when ring was full 😭
• the number of entries in the buffer, as of the exact point in time that entry is enqueued, gets stored in the integer that length points at 💅

👀 SEE ALSO 👀

• ck_ring_init(3)
• ck_ring_dequeue_spmc(3)
• ck_ring_trydequeue_spmc(3)
• ck_ring_enqueue_spmc(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 is available at http://concurrencykit.org/ 🌈

and that's the page, bestie!! 💖 this was the CK_RING_ENQUEUE_SPMC_SIZE(3) manual, dated April 20, 2013 — yeah she's an old queen and she still slays 👑 go forth and enqueue responsibly, mwah 🎀✨💅