qthread_queue_create(3)

✨ qthread_queue_create — bestie we're building sync queues ✨

okay so this page lives in the libqthread manual, and it's all about qthread_queue_create(3) and its partner in crime qthread_queue_destroy(3). pull up a chair, we're gonna talk about synchronization queues 💅

🌸 NAME 🌸

qthread_queue_create — allocate and/or initialize a synchronization queue 🎀

🦋 SYNOPSIS 🦋

#include <qthread.h>

qthread_queue_t
qthread_queue_create (uint8_t flags,
                      aligned_t length);

int
qthread_queue_destroy (qthread_queue_t q);

💖 DESCRIPTION 💖

so these two functions are the allocating and deallocating girlies for qthread_queue_t objects. qthread_queue_create() allocates and initializes a qthread_queue_t object, and qthread_queue_destroy() deallocates one. periodt. 🫶

these objects are generic synchronization building blocks — like, they're designed specifically for implementing other synchronization objects. you can use them to implement mutexes, FEBs, and even sincs, and it's actually pretty efficient, given that you also have to initialize and destroy the associated bookkeeping structure. the only thing that changes between all those use cases is how the queue is used. iykyk ✨

the creation function takes two arguments: flags and length. the flags may be any of the following:

• QTHREAD_QUEUE_NO_SYNC — this says the queue should employ no synchronization. all the sync gets done externally, if you even need it, to make sure access to both joining and releasing the queue is exclusive. the queue can have any number of entries. no cap.
• QTHREAD_QUEUE_MULTI_JOIN — this says the queue should expect to have multiple concurrent, asynchronous join operations. those join operations are safe to execute in parallel, but the release operation is not safe to run in parallel with the join operations. the queue can have any number of entries.
• QTHREAD_QUEUE_MULTI_JOIN_LENGTH — same energy as above: the queue should expect multiple concurrent, asynchronous join operations, and it should keep track of the length of the queue. those joins are safe to execute in parallel, but again, the release operation is not safe to run in parallel with the joins. the queue can have any number of entries.
• QTHREAD_QUEUE_CAPPED — this one says the queue should, like the MULTI_JOIN options, be safe to join in parallel, but also that there's a maximum number of elements in the queue. the slay here is that it lets the join operation be faster, because it doesn't need to allocate memory. 🔥

the length argument is only applicable for QTHREAD_QUEUE_CAPPED, and it specifies the fixed length of the queue. that's it, that's the whole job.

🌈 RETURN VALUES 🌈

• qthread_queue_create() returns an initialized qthread_queue_t object. iconic. 👑
• qthread_queue_destroy() returns QTHREAD_SUCCESS on success, and an error otherwise. 😭

🎀 SEE ALSO 🎀

• qthread_queue_destroy(3)
• qthread_queue_join(3)
• qthread_queue_length(3)
• qthread_queue_release_all(3)
• qthread_queue_release_one(3)

go read those too bestie, they're the whole friend group 🦋

and that's the vibe check, bestie 💖 this page came from libqthread, dated AUGUST 2013 — yeah it's a vintage queen but she still ate. now go forth and build your synchronization objects, main character. mwah 💅✨