qarray_create(3)

💖 qarray_create — allocate a runtime distributed array 💖

okay bestie, welcome to qarray_create(3) from libqthread 🌸 this one's a lil trio of functions that spin up distributed array objects for you. stay with me, it's giving main character energy fr fr.

✨ NAME ✨

qarray_create — allocate a runtime distributed array 🫶

🎀 SYNOPSIS 🎀

#include <qthread/qarray.h>

qarray *
qarray_create (const size_t count, const size_t unit_size);

qarray *
qarray_create_tight (const size_t count, const size_t unit_size);

qarray *
qarray_create_configured (const size_t count, const size_t unit_size,
                          const distribution_t d, const char tight,
                          const int seg_pages);

🌈 DESCRIPTION 🌈

so these three functions all initialize qarray distributed array objects. no cap. all three of them create an array that holds at least count elements, and each element is at least unit_size bytes long. 💅

now here's the tea on the differences:

• qarray_create() may round that element size up to the next-largest multiple of eight.
• qarray_create_tight() is guaranteed NOT to do that, so the elements end up packed tightly in the array. slay.
• qarray_create_configured() gives you way more control over how the array is actually implemented — you get to specify the distribution pattern (d) and the length of the distributed array segments (seg_pages).

about that seg_pages argument, bestie: it's the number of memory pages in a single segment. memory literally cannot be distributed in units smaller than a single page, so that's the floor. and if seg_pages is zero, a default value gets chosen for you. ✨

the possible values for d are, in order:

• FIXED_HASH — distributes the memory across the available shepherds evenly, using a basic round-robin assignment mechanism based on the address of the initial page of each segment. Array segments cannot be relocated.
• FIXED_FIELDS — distributes the memory evenly across all shepherds, keeping long contiguous sets of segments on each shepherd. Segment locations are defined by a simple math operation on the index, so array segments cannot be relocated.
• ALL_LOCAL — assigns the entire array to the local shepherd. Array segments cannot be relocated.
• ALL_RAND — assigns the entire array to a random shepherd. Array segments cannot be relocated.
• ALL_LEAST — assigns the entire array to the shepherd with the least qarray segments currently assigned to it. Array segments cannot be relocated.
• DIST_STRIPES — assigns array segments with a round-robin mechanism. Segment location is stored in the segment, so segments can be relocated, but finding a segment requires extra memory operations. 😭
• DIST_FIELDS — assigns array segments evenly across all shepherds, attempting to maintain long contiguous sets of segments on each shepherd. Segment location is stored in the segment, so segments can be relocated, but finding a segment requires extra memory operations. 😭
• DIST_RAND — assigns array segments randomly to shepherds. Segment location is stored in the segment, so segments can be relocated, but finding a segment requires extra memory operations. 😭
• DIST_LEAST — assigns each array segment to whichever shepherd has the fewest array segments assigned to it at creation time. Segment location is stored in the segment, so segments can be relocated, but finding a segment requires extra memory operations. 😭

ngl the pattern is kinda iconic: the FIXED_* and ALL_* ones lock your segments in place, and the DIST_* ones let segments move around but charge you extra memory ops to find them. iykyk 💅

👑 SEE ALSO 👑

qarray_destroy(3), qarray_iter(3), qarray_shepof(3), qarray_elem(3)

and that's the whole vibe check, bestie 💖 this page comes from libqthread, dated MAY 2009 — a whole era, honestly. go forth and distribute ur arrays. 🦋✨