HWLOC-DISTRIB(1)
NAME
hwloc-distrib - Build a number of cpu masks distributed on the system
SYNOPSIS
topodistrib [options] <integer>
OPTIONS
- --single
- Singlify each output to a single CPU.
- -v Verbose messages.
- --xml <path>
- Read topology from XML file <path> (instead of discovering the topology on the local machine). If <path> is "-", the standard input is used. XML support must have been compiled in to hwloc for this option to be usable.
- --synthetic <specification>
- Simulate a fake hierarchy (instead of discovering the topology on the local machine). If <specification> is "node:2 pu:3", the topology will contain two NUMA nodes with 3 processing units in each of them.
- --version
- Report version and exit.
DESCRIPTION
hwloc-distrib generates a series of CPU masks in an attempt to distribute a set of processes around multiple processors in a single server.
These masks can be used with hwloc-bind(1).
NOTE: It is highly recommended that you read the hwloc(7) overview page
before reading this man page. Most of the concepts described in
hwloc(7) directly apply to the hwloc-bind utility.
EXAMPLES
hwloc-distrib's operation is best described through several examples.
- If 4 processes have to be distributed across a machine, their CPU masks
may be obtained with:
- $ hwloc-distrib 4
0x0000000f
0x00000f00
0x000000f0
0x0000f000 - To get a single processor of each CPU masks (prevent migration in case of binding)
$ hwloc-distrib 4 --single
0x00000001
0x00000100
0x00000010
0x00001000- Each output line may be converted independently with hwloc-calc and xargs:
$ hwloc-distrib 4 --single | xargs -n 1 hwloc-calc --objects
PU:0
PU:1
PU:2
PU:3- To convert the output into a list of processors that may be passed to dplace -c inside a mpirun command line:
$ hwloc-distrib 4 --single | xargs hwloc-calc --pulist
0,8,4,16
RETURN VALUE
Upon successful execution, hwloc-distrib displays one or more CPU mask
strings. The return value is 0.
hwloc-distrib will return nonzero if any kind of error occurs, such as
(but not limited to) failure to parse the command line.