---
name: "hwloc_distrib_flags_e"
section: "3"
platform: "linux"
package: "hwloc"
version: "2.15.0-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/hwlocality_helper_distribute"
---

# hwloc\_distrib\_flags\_e(3)

Distributing items over a topology

Part of [hwlocality\_helper\_distribute(3)](/hwlocality_helper_distribute/3.md).

## 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.