qt_loop_queue_create(3)

💖 qt_loop_queue_create — a libqthread joint, section 3, bestie 💖

okay so real quick: this page lives in the libqthread manual, section 3, and it's literally all about one function. sit down, grab a strawberry 🍓, we're doing this.

✨ NAME ✨

qt_loop_queue_create — allocate a loop queue handle 🎀

🦋 SYNOPSIS 🦋

#include <qthread/qloop.h>

qqloop_handle_t*
qt_loop_queue_create(
       const qt_loop_queue_type type,
       const size_t start,
       const size_t stop,
       const size_t step,
       const qt_loop_f func,
       void * const argptr);

that's the whole vibe right there, no cap 💅

🌸 DESCRIPTION 🌸

so this function allocates a loop queue handle that you then get to use with qt_loop_queue_run() or qt_loop_queue_run_there(). it's giving "make me a handle so i can actually run the thing" ✨

okay now the important part, bestie. the func argument has to be a function pointer with a qt_loop_f prototype, and its basic code structure is expected to look like this:

void func (const size_t startat, const size_t stopat, const
size_t step, void * arg)
{
       for (unsigned int i = startat; i < stopat; i += step) {
              /* do work */
       }
}

so startat and stopat? those are decided by the library, not you 🫶 the library tells your function which range of i values (aka iterations) it's responsible for. you don't pick, you just vibe with what you're handed.

now the type argument — this one is the main character honestly. it defines which adaptive scheduling technique gets used to schedule the processing of loop iterations. the possible values are:

• CHUNK — the lowest-overhead method, but also the least adaptive. the library picks a small default chunk size, and all the available worker threads chew through loop iterations in groups of that size. you can set the chunk size yourself with qt_loop_queue_setchunk(). simple, speedy, not fancy 💀
• GUIDED — an implementation of guided self-scheduled loops, invented by Constantine D. Polychronopoulos and David J. Kuck back in 1987. iterations run in chunks that get halved in size as the loop progresses. this is particularly efficient at slightly imbalanced loops — it's giving "i adjust, but gently" 🌈
• FACTORED — an implementation of factored self-scheduled loops, invented by Susan F. Hummel, and Edith Schonberg, and Lawrence E. Flynn in 1992. iterations run in chunks specified in sets. first, half of the iteration space is handed out in equal-sized chunks to all threads, then half of the remaining iterations get handed out in equal-sized chunks, and so forth. this is more effective than GUIDED when loops are more imbalanced 🔥
• TIMED — an implementation of timed self-scheduled loops. iterations get timed, and subsequent chunks of iterations are given to worker threads based on how long the previous iteration chunks took. this method can account for overhead better and can potentially handle wildly imbalanced loops more efficiently than FACTORED. the overachiever of the group, honestly 👑

💜 RETURN VALUES 💜

you get a pointer to a valid qqloop_handle_t back OR a NULL pointer if memory could not be allocated. that's it, that's the deal. if you see NULL, bestie, memory said no 🙈

🧚 SEE ALSO 🧚

• qt_loop(3)
• qt_loop_queue_run(3)
• qt_loopaccum_balance(3)

and that's the whole page!! go forth and queue your loops, you absolute icon 💅✨

libqthread · APRIL 2011 · qt_loop_queue_create(3) — periodt, that's a wrap 🎀💖