qarray_iter(3)

💖 qarray_iter — iterate through a distributed array 💖

okay so bestie, welcome to qarray_iter(3), part of the libqthread manual 💅 this one's all about yeeting your function across a distributed array and letting it run right next to the data, which is the whole vibe. no cap. 🦋

✨ NAME ✨

qarray_iter — iterate through a distributed array 🎀

🌸 SYNOPSIS 🌸

#include <qthread/qarray.h>

void
qarray_iter (qarray *a, const size_t startat,
             const size_t stopat, qthread_f func);

void
qarray_iter_loop (qarray *a, const size_t startat,
                  const size_t stopat, qa_loop_f func,
                  void *arg);

void
qarray_iter_loop_nb (qarray *a, const size_t startat,
                  const size_t stopat, qa_loop_f func,
                  void *arg, aligned_t *arg);

void
qarray_iter_constloop (qarray *a, const size_t startat,
                       const size_t stopat, qa_loop_f func,
                       void *arg);

void
qarray_iter_loopaccum (qarray *a, const size_t startat,
                       const size_t stopat, qa_loopr_f func,
                       void *arg, void *ret, const size_t retsize,
                       qt_accum_f acc);

💜 DESCRIPTION 💜

so these functions iterate efficiently over distributed arrays, and honestly? iconic. ✨

the most basic and naive one of the whole set is qarray_iter(). it applies the func function to every single element in the array, and it guarantees that the function will be executed near the specified data — like, it's literally right there, no long-distance situationship. 🫶

the func function here is a basic qthread function, shaped like this:

void func (void *arg);

and the arg argument that gets handed to func is a pointer to an array element. periodt. 💅

🦋 the fancier ones 🦋

okay so qarray_iter_loop(), qarray_iter_loop_nb(), qarray_iter_constloop(), and qarray_iter_loopaccum() are the more powerful iteration functions. they're largely identical to each other, with these little distinctions:

• qarray_iter_constloop() forbids modifying the input qarray — hands off, no touching, it's giving look-don't-touch energy 🙈
• qarray_iter_loopaccum() requires an accumulator function, acc, and it lets you calculate an accumulated value similar to qt_loopaccum_balance() 👑

both of those functions iterate over a range of values within the qarray, and that range is defined by the startat and stopat arguments.

the func argument is expected to be a function shaped like this:

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

so func gets handed a sub-range of the qarray to iterate over — not the whole thing, just its little slice, and it goes off and does its thing. 🍓

the arg argument passed to the func function is the same argument as is passed to the qarray_iter_loop() argument. (yes, fr fr, that's the deal.)

and the qarray_iter_loop_nb() variant? that one lets the iterations happen in the background while the calling thread just... continues executing. main character energy, honestly. ✨

🌈 SEE ALSO 🌈

• qarray_create(3)
• qarray_destroy(3)
• qarray_shepof(3)
• qarray_elem(3)

okay bestie that's the whole page, go iterate something gorgeous 💖

libqthread · APRIL 2011 — mwah, that's a wrap on qarray_iter(3), slay 💅✨