hwlocality...distribute(3)

hwlocality...distribute(3) 🦋

okay so bestie, welcome to the Library Functions Manual page for hwlocality...distribute(3) — yes, the name is a whole mouthful, but she's giving distributing items over a topology and we're obsessed ✨

✨ NAME ✨

hwlocality_helper_distribute — literally distributing items over a topology 💅 periodt.

✨ SYNOPSIS ✨

Enumerations

enum hwloc_distrib_flags_e { HWLOC_DISTRIB_FLAG_REVERSE }

Functions

int hwloc_distrib (hwloc_topology_t topology, hwloc_obj_t *roots,
    unsigned n_roots, hwloc_cpuset_t *set, unsigned n, int until,
    unsigned long flags)

✨ Detailed Description ✨

No extra prose under this one in the original, bestie — we're going straight to the docs 💖

✨ Enumeration Type Documentation ✨

enum hwloc_distrib_flags_e

Flags to be given to hwloc_distrib().

Enumerator

• HWLOC_DISTRIB_FLAG_REVERSE — Distrib in reverse order, starting from the last objects.

✨ Function Documentation ✨

int hwloc_distrib (hwloc_topology_t topology, hwloc_obj_t * roots, unsigned
    n_roots, hwloc_cpuset_t * set, unsigned n, int until, unsigned long
    flags) [inline]

Distribute n items over the topology under roots — the array set will be filled with n cpusets recursively distributed linearly over the topology under the objects roots, down to depth until (which can be INT_MAX to distribute down to the finest level 🫶).

n_roots is usually 1 and roots only contains the topology root object so as to distribute over the entire topology ✨.

This is typically useful when an application wants to distribute n threads over a machine, giving each of them as much private cache as possible and keeping them locally in number order — main character scheduling energy 👑.

The caller may typically want to also call hwloc_bitmap_singlify() before binding a thread so that it does not move at all 💅.

flags should be 0 or a OR'ed set of hwloc_distrib_flags_e.

Returns

0 on success, -1 on error.

Note

On hybrid CPUs (or asymmetric platforms), distribution may be suboptimal since the number of cores or PUs inside packages or below caches may vary (the top-down recursive partitioning ignores these numbers until reaching their levels). Hence it is recommended to distribute only inside a single homogeneous domain. For instance on a CPU with energy-efficient E-cores and high-performance P-cores, one should distribute separately N tasks on E-cores and M tasks on P-cores instead of trying to distribute directly M+N tasks on the entire CPUs.

This function requires the roots objects to have a CPU set.

✨ Author ✨

Generated automatically by Doxygen for Hardware Locality (hwloc) from the source code — iconic, no notes 💖

---

okay bestie, that's the whole page 💅 — cute sign-off: this one comes from Hardware Locality (hwloc), Version 2.15.0. The footer doesn't show a date, so we're not inventing one — stay distributed and hydrated! 🫶✨