hwlocality...distribute(3) Library Functions Manual hwlocality...distribute(3)
NAME
hwlocality_helper_distribute - Distributing items over a topology
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
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. Array set will be
filled with n cpusets recursively distributed linearly over the topology
under 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.
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.
Hardware Locality (hwloc) Version 2.12.0 hwlocality...distribute(3)
Generated by dwww version 1.16 on Thu Oct 15 12:41:36 CEST 2026.