Python rrun API Reference

Resource binding utilities from the rrun launcher.

class rapidsmpf.rrun.BindingValidation(

cpu_ok: bool,

numa_ok: bool,

ucx_ok: bool,

expected_ucx_devices: str,

)

Results of validating actual vs. expected resource bindings.

Parameters:

cpu_ok

CPU affinity check passed.

numa_ok

NUMA binding check passed.

ucx_ok

UCX network devices check passed.

expected_ucx_devices

Expected UCX devices as a comma-separated string.

Methods

all_passed(self)

Return True if all validation checks passed.

See also

validate_binding

Produce a validation result.

all_passed(self) → bool

Return True if all validation checks passed.

class rapidsmpf.rrun.ExpectedBinding(

cpu_affinity: str = '',

memory_binding: list[int] = <factory>,

network_devices: list[str] = <factory>,

)

Expected resource binding derived from topology information.

Represents the binding configuration that should be in effect for a given GPU according to the system topology.

Parameters:

cpu_affinity

Expected CPU affinity list.

memory_binding

Expected NUMA node IDs.

network_devices

Expected network devices.

See also

validate_binding

Compare actual vs. expected bindings.

class rapidsmpf.rrun.ResourceBinding(

rank: int | None,

gpu_id: int | None,

gpu_pci_bus_id: str,

cpu_affinity: str,

numa_nodes: list[int],

ucx_net_devices: str,

)

Live resource binding configuration collected from the running process.

Holds the CPU affinity, NUMA memory binding, and network device configuration that are currently in effect.

Parameters:

rank

Process rank, or None if not available.

gpu_id

GPU device ID, or None if not available.

gpu_pci_bus_id

GPU PCI bus ID (empty if unavailable).

cpu_affinity

CPU affinity string (e.g., "0-19,40-59").

numa_nodes

NUMA node IDs bound to this process.

ucx_net_devices

Value of the UCX_NET_DEVICES environment variable.

See also

check_binding

Collect the live binding of the calling process.

rapidsmpf.rrun.bind(gpu_id=None, *, cpu=True, memory=True, network=True, verify=True)

Bind the calling process to resources topologically close to a GPU.

Discovers the system topology, then applies CPU affinity, NUMA memory binding, and/or network device configuration as requested.

Warning

This function is not thread-safe. It temporarily modifies the CUDA_VISIBLE_DEVICES environment variable during topology discovery and mutates process-wide state (CPU affinity, NUMA memory policy, and the UCX_NET_DEVICES environment variable). It should be called exactly once per process, ideally early in initialization and before other threads are spawned.

GPU resolution order:

1. Use gpu_id if provided.

2. Otherwise, parse the first entry of the CUDA_VISIBLE_DEVICES environment variable.

3. If neither is available, raise RuntimeError.

Parameters:

gpu_id

Physical GPU device index (as reported by nvidia-smi). When None, the first GPU in CUDA_VISIBLE_DEVICES is used.

cpu

Set CPU affinity to cores near the GPU (default True).

memory

Set NUMA memory policy to nodes near the GPU (default True).

network

Set UCX_NET_DEVICES to NICs near the GPU (default True).

verify

Read back and verify that bindings match the requested configuration after applying them (default True).

Raises:

RuntimeError

If no GPU ID can be determined, topology discovery fails, the resolved GPU is not found in the discovered topology, an enabled CPU or network binding could not be applied, a NUMA memory policy operation fails unexpectedly, or post-bind verification detects a mismatch between the requested and actual state. NUMA memory binding is skipped when the current OS/container does not allow memory-policy syscalls or the requested node is outside the task’s allowed memory nodes.

ValueError

If gpu_id is not a non-negative integer.

rapidsmpf.rrun.check_binding(gpu_id_hint=None)

Collect the live resource binding of the calling process.

Queries the current CPU affinity, NUMA memory nodes, UCX network device configuration, process rank, and GPU information. Fields that cannot be determined (e.g. rank when no launcher environment is set, or GPU ID when CUDA_VISIBLE_DEVICES is absent and no hint is given) are returned as None.

Parameters:

gpu_id_hint

GPU device index hint. When a non-negative integer the value is stored directly; when None the GPU ID is read from CUDA_VISIBLE_DEVICES. When a valid GPU ID is available the PCI bus ID is also queried.

Returns:

ResourceBinding

The collected resource binding.

rapidsmpf.rrun.validate_binding(actual, expected)

Validate an actual resource binding against an expected one.

Compares the live actual binding with expected and reports per-resource pass/fail status.

Parameters:

actualResourceBinding

Live resource binding (from check_binding()).

expectedExpectedBinding

Expected binding (from topology or another source).

Returns:

BindingValidation

Per-resource validation results.