rrun#

resource_binding rapidsmpf::rrun::check_binding(int gpu_id_hint = -1)#

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 left at their default value of -1.

Parameters:: gpu_id_hint – GPU device index hint. When >= 0 the value is stored directly; otherwise the GPU ID is read from CUDA_VISIBLE_DEVICES. When a valid GPU ID is available, the PCI bus ID is also queried.
Returns:: The collected resource binding.

std::optional<expected_binding> rapidsmpf::rrun::get_expected_binding( cucascade::memory::system_topology_info const &topology, int gpu_id )#

Obtain the expected binding for a GPU from pre-discovered topology.

Looks up gpu_id in topology and returns the expected CPU affinity, memory binding, and network devices.

Parameters:

topology – Pre-discovered system topology.
gpu_id – GPU device index to look up.

Returns:

The expected binding, or std::nullopt if gpu_id is not found.

binding_validation rapidsmpf::rrun::validate_binding( resource_binding const &actual, expected_binding const &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:

actual – Live resource binding (from check_binding()).
expected – Expected binding (from topology or a JSON file).

Returns:

Validation results.

void rapidsmpf::rrun::bind( std::optional<unsigned int> gpu_id = std::nullopt, bind_options const &options = {} )#

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

Discovers the system topology via cucascade::memory::topology_discovery, then applies CPU affinity, NUMA memory binding, and/or network device configuration as requested in options.

This is the self-contained entry point intended for external libraries that do not launch through the rrun CLI.

GPU resolution order:

Use gpu_id if provided.
Otherwise, parse the first entry of the CUDA_VISIBLE_DEVICES environment variable.
If neither is available, throw std::runtime_error.

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.

Parameters:

gpu_id – GPU device index (as reported by nvidia-smi) to bind for. When std::nullopt, the first GPU in CUDA_VISIBLE_DEVICES is used instead.
options – Controls which resource bindings to apply.

Throws:

std::runtime_error – 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 binding 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.

void rapidsmpf::rrun::bind( cucascade::memory::system_topology_info const &topology, std::optional<unsigned int> gpu_id = std::nullopt, bind_options const &options = {} )#

Bind using pre-discovered topology information.

Same as the other overload, but skips the topology discovery step by reusing a previously obtained system_topology_info. Useful when the caller has already performed discovery (e.g., in a parent process before forking).

GPU resolution follows the same order as the other overload (explicit gpu_id, then CUDA_VISIBLE_DEVICES).

Warning

This function is not thread-safe. It 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.

Parameters:

topology – Pre-discovered system topology.
gpu_id – GPU device index to bind for. When std::nullopt, the first GPU in CUDA_VISIBLE_DEVICES is used instead.
options – Controls which resource bindings to apply.

Throws:

std::runtime_error – if no GPU ID can be determined, the resolved GPU is not found in 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 binding 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.

struct bind_options#

#include <rrun.hpp>

Options controlling which topology-based resource bindings to apply.

By default all bindings are enabled. Pass a custom instance to bind() to selectively enable or disable individual resource classes.

Public Members

bool cpu = {true}#: Set CPU affinity to cores near the GPU.

bool memory = {true}#: Set NUMA memory policy to nodes near the GPU.

bool network = {true}#: Set UCX_NET_DEVICES to NICs near the GPU.

bool verify = {true}#: Read back and verify bindings after applying them.

struct resource_binding#

#include <rrun.hpp>

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. Obtained via check_binding().

Public Members

int rank = -1#: Process rank (-1 if not available).

int gpu_id = -1#: GPU device ID (-1 if not available).

std::string gpu_pci_bus_id#: GPU PCI bus ID (empty if unavailable).

std::string cpu_affinity#: CPU affinity string (e.g., “0-19,40-59”).

std::vector<int> numa_nodes#: NUMA node IDs bound to this process.

std::string ucx_net_devices#: Value of the UCX_NET_DEVICES env var.

struct expected_binding#

#include <rrun.hpp>

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.

Public Members

std::string cpu_affinity#: Expected CPU affinity list.

std::vector<int> memory_binding#: Expected NUMA node IDs.

std::vector<std::string> network_devices#: Expected network devices.

struct binding_validation#

#include <rrun.hpp>

Results of validating actual vs. expected resource bindings.

Public Functions

inline bool all_passed() const#

Check if all validations passed.

Returns:: true if CPU, NUMA, and UCX checks all passed.

Public Members

bool cpu_ok = true#: CPU affinity check passed.

bool numa_ok = true#: NUMA binding check passed.

bool ucx_ok = true#: UCX network devices check passed.

std::string expected_ucx_devices#: Expected UCX devices (comma-separated).

class ScopedEnvVar#

#include <scoped_env_var.hpp>

RAII guard that saves, optionally modifies, and restores an environment variable.

On construction the current value of the named variable is captured. The caller may pass an initial value to set, or nullptr to unset the variable. On destruction the original state is restored unconditionally, making this class safe to use across code that may throw.

{
    ScopedEnvVar guard("CUDA_VISIBLE_DEVICES", nullptr);  // unset
    // ... topology discovery sees all GPUs ...
}  // original CUDA_VISIBLE_DEVICES restored here

Public Functions

inline ScopedEnvVar(char const *name, char const *value)#

Construct the guard, saving and optionally replacing the variable.

Parameters:

name – Name of the environment variable.
value – Value to set, or nullptr to unset the variable.