hwlocality\_helper\_distribute(3) Library Functions Manual hwlocality\_helper\_distribute(3)

# [NAME](#NAME)

hwlocality\_helper\_distribute - Distributing items over a topology

# [SYNOPSIS](#SYNOPSIS)

## [Enumerations](#Enumerations)

enum **hwloc\_distrib\_flags\_e** { **HWLOC\_DISTRIB\_FLAG\_REVERSE** }

## [Functions](#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](#Detailed_Description)

# [Enumeration Type Documentation](#Enumeration_Type_Documentation)

## [enum **hwloc\_distrib\_flags\_e**](#enum_)

Flags to be given to **hwloc\_distrib()**.

**Enumerator**

[***HWLOC\_DISTRIB\_FLAG\_REVERSE***](#HWLOC_DISTRIB_FLAG_REVERSE)

Distrib in reverse order, starting from the last objects.

# [Function Documentation](#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\]](#int_hwloc_distrib_%28)

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](#Author)

Generated automatically by Doxygen for Hardware Locality (hwloc) from the source code.

Version 2.15.0 Hardware Locality (hwloc)

---

Document: HWLOC_DISTRIB_FLAG_REVERSE(3) from hwloc-cuda-12.8 2.15.0-r0 (Chainguard OS)
Source: https://github.com/open-mpi/hwloc