CK_RING_ENQUEUE_SPSC(3)

✨ CK_RING_ENQUEUE_SPSC(3) ✨

okay bestie, welcome to the CK_RING_ENQUEUE_SPSC(3) page 💖 this is the Concurrency Kit girlies' guide to yeeting a pointer into a bounded FIFO, and honestly? it's giving main character energy. let's get into it 🫶

🌸 NAME 🌸

ck_ring_enqueue_spsc — enqueue pointer into bounded FIFO 🎀

💜 LIBRARY 💜

Concurrency Kit (that's libck, and you link it with -lck, iykyk) 💅

🦋 SYNOPSIS 🦋

#include <ck_ring.h>

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

✨ DESCRIPTION ✨

so like, the ck_ring_enqueue_spsc(3) function enqueues the pointer entry into the bounded buffer pointed to by ring, and it does it in FIFO fashion — first in, first out, no cutting the line bestie 🎀

the buffer pointed to by buffer must be unique to ring and must point to an array of ck_ring_buffer_t of sufficient length (that length is according to the power-of-2 elements in the buffer). no cap, that part is important 👑

the whole decoupling-the-ring-from-the-buffer situation? it's not just for the aesthetic ✨ it serves to address use-cases involving multiple address spaces and DMA, among others. iconic design choice, honestly.

if you're on non-POSIX platforms, or you just wish for strict compliance with C, then it is recommended that you pass a pointer of type void ** for entry. 🌈

this function is safe to call without locking for up to one concurrent invocation of ck_ring_dequeue_spsc(3). and the best part? this function provides wait-free progress guarantees 🧚 periodt.

💖 EXAMPLE 💖

here's the vibe, 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_spsc(&ring, &buffer, &entry) == false) {
                /*
                 * The buffer was full and the enqueue operation
                 * has failed.
                 */
                return;
        }

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

🔥 RETURN VALUES 🔥

• the function returns true if the value of entry was successfully enqueued into ring. slay 💅
• the function returns false if the value of entry could not be enqueued — and that only happens if ring was full. so if you got a false, your ring was packed, no room, sorry babe 😭

🌈 SEE ALSO 🌈

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

additional information is available at http://concurrencykit.org/ — go read it, bestie, it's worth it 💜

okay that's the whole page!! 🎀 this was CK_RING_ENQUEUE_SPSC(3) from Concurrency Kit, dated April 20, 2013 — literally a classic, an icon, a legend, and she still ate 💅✨ bye bestie, go enqueue something 🦋