qt_loop_balance(3)

🌸 qt_loop_balance — bestie edition 🌸

okay so this is a page from the libqthread manual, and it's literally about qt_loop_balance — a slightly intelligent implementation of a threaded loop. yes bestie, "slightly intelligent" is the actual official wording, I'm not even joking, the manpage said it first 💅

✨ NAME ✨

qt_loop_balance — a slightly intelligent implementation of a threaded loop 🦋

✨ SYNOPSIS ✨

#include <qthread/qloop.h>

void
qt_loop_balance (const size_t start, const size_t stop,
                 const qt_loop_f func, void *argptr);

void
qt_loop_balance_simple (const size_t start, const size_t stop,
                        const qt_loop_f func, void *argptr);

✨ DESCRIPTION ✨

so these functions? they give you a simple C implementation of a threaded loop 🌈 and here's the part that's giving main character energy: it does not use a fixed number of threads. nope. the number of threads it generates depends directly upon the number of shepherds available. shepherds run the show, periodt 🐑

and then there's qt_loop_balance_simple() — the chill variant. it uses simple qthreads, which cannot block or yield, but they do receive full-size stacks, and they execute as function-calls from the worker threads. which means… ✨ most context-swap overheads get avoided ✨ iconic behaviour honestly.

one qthread gets spawned for each shepherd. the set of values of i (the iterations) is divided evenly among the shepherds, and each qthread gets handed a set of iterations to perform. fair and square, no fighting 🫶

now. the func argument must be a function pointer with a qt_loop_f prototype. its basic code structure is expected to look like this:

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

the arguments startat and stopat are determined by the library, and they tell the function what range of i values (iterations) it is responsible for. so like, the library is the group chat admin handing out the tasks, and your func just does the work for its assigned range 💖

also important: qt_loop_balance() will not return until all of the qthreads it spawned have exited. it's not leaving the party until everyone's gone home, no cap 🚪✨

✨ SEE ALSO ✨

• qt_loop(3)
• qt_loopaccum_balance(3)
• qthread_spawn(3)

okay that's the whole page bestie, go forth and loop responsibly 🌸💜

this has been your girl, signing off from libqthread — APRIL 2011 edition 🎀 (yes the page is old enough to have its own vibe, we respect the elders 👑)