Struct NixlAgent

Source

pub struct NixlAgent { /* private fields */ }

Expand description

A NIXL agent wrapper that tracks which backends were successfully initialized.

This wrapper provides:

Runtime validation of backend availability
Clear error messages when operations need unavailable backends
Single source of truth for backend state in tests and production

§Backend Tracking

Since nixl_sys::Agent doesn’t provide a method to query active backends, we track them during initialization. The available_backends set is populated based on successful create_backend() calls.

Implementations§

Source §

impl NixlAgent

Source

pub fn new(name: &str) -> Result<Self>

Create a NIXL agent without any backends.

Source

pub fn from_nixl_backend_config( name: &str, config: NixlBackendConfig, ) -> Result<Self>

Creates a new agent configured with backends from the given config.

This method iterates over all backends in the config and initializes them with their associated parameters. If a backend has custom parameters defined in the config, those are used; otherwise, default plugin parameters are used.

Source

pub fn add_backend(&mut self, backend: &str) -> Result<()>

Add a backend to the agent with default parameters.

Source

pub fn add_backend_with_params( &mut self, backend: &str, custom_params: &HashMap<String, String>, ) -> Result<()>

Add a backend to the agent with optional custom parameters.

If custom_params is non-empty, those parameters are used instead of the plugin defaults. If empty, default parameters from the plugin are used.

§Errors

Returns an error if custom parameters are provided (not yet supported until nixl_sys 0.9).

Source

pub fn with_backends(name: &str, backends: &[&str]) -> Result<Self>

Create a NIXL agent requiring ALL specified backends to be available.

Unlike new_with_backends() which continues if some backends fail, this method will return an error if ANY backend fails to initialize. Use this in production when specific backends are mandatory.

§Arguments

name - Agent name
backends - List of backend names that MUST be available

§Returns

A NixlAgent with all requested backends initialized.

§Errors

Returns an error if:

Agent creation fails
Any backend fails to initialize

Source

pub fn raw_agent(&self) -> &Agent

Get a reference to the underlying raw NIXL agent.

Source

pub fn into_raw_agent(self) -> Agent

Consume and return the underlying raw NIXL agent.

Warning: Once consumed, backend tracking is lost. Use this only when interfacing with code that requires nixl_sys::Agent directly.

Source

pub fn has_backend(&self, backend: &str) -> bool

Check if a specific backend is available.

Source

pub fn backends(&self) -> &HashSet<String>

Get all available backends.

Source

pub fn require_backend(&self, backend: &str) -> Result<()>

Require a specific backend, returning an error if unavailable.

Use this at the start of operations that need specific backends.

Note: In general, you want to instantiate all your backends before you start registering memory. We may change this to a builder pattern in the future to enforce all backends are instantiated before you start registering memory.

Methods from Deref<Target = Agent>§

Source

pub fn name(&self) -> String

Gets the name of the agent

Source

pub fn get_available_plugins(&self) -> Result<StringList, NixlError>

Gets the list of available plugins

Source

pub fn get_plugin_params( &self, plugin_name: &str, ) -> Result<(MemList, Params), NixlError>

Gets the parameters for a plugin

§Arguments

plugin_name - The name of the plugin

§Returns

The plugin’s memory list and parameters

§Errors

Returns a NixlError if:

The plugin name contains interior nul bytes
The operation fails

Source

pub fn create_backend( &self, plugin: &str, params: &Params, ) -> Result<Backend, NixlError>

Creates a new backend for the given plugin using the provided parameters

Source

pub fn get_backend(&self, name: &str) -> Option<Backend>

Gets a backend by name

Source

pub fn get_backend_params( &self, backend: &Backend, ) -> Result<(MemList, Params), NixlError>

Gets the parameters and memory types for a backend after initialization

Source

pub fn register_memory( &self, descriptor: &impl NixlDescriptor, opt_args: Option<&OptArgs>, ) -> Result<RegistrationHandle, NixlError>

Registers a memory descriptor with the agent

§Arguments

descriptor - The memory descriptor to register
opt_args - Optional arguments for the registration

Source

pub fn query_mem( &self, descs: &RegDescList<'_>, opt_args: Option<&OptArgs>, ) -> Result<QueryResponseList, NixlError>

Query information about memory/storage

§Arguments

descs - Registration descriptor list to query
opt_args - Optional arguments specifying backends

§Returns

A list of query responses, where each response may contain parameters describing the memory/storage characteristics.

Source

pub fn get_local_md(&self) -> Result<Vec<u8>, NixlError>

Gets the local metadata for this agent as a byte array

Source

pub fn get_local_partial_md( &self, descs: &RegDescList<'_>, opt_args: Option<&OptArgs>, ) -> Result<Vec<u8>, NixlError>

Gets the local partial metadata as a byte array

§Arguments

descs - Registration descriptor list to get metadata for
opt_args - Optional arguments for getting metadata

§Returns

A byte array containing the local partial metadata

Source

pub fn load_remote_md(&self, metadata: &[u8]) -> Result<String, NixlError>

Loads remote metadata from a byte slice

Source

pub fn make_connection( &self, remote_agent: &str, opt_args: Option<&OptArgs>, ) -> Result<(), NixlError>

Source

pub fn prepare_xfer_dlist( &self, agent_name: &str, descs: &XferDescList<'_>, opt_args: Option<&OptArgs>, ) -> Result<XferDlistHandle, NixlError>

Source

pub fn make_xfer_req( &self, operation: XferOp, local_descs: &XferDlistHandle, local_indices: &[i32], remote_descs: &XferDlistHandle, remote_indices: &[i32], opt_args: Option<&OptArgs>, ) -> Result<XferRequest, NixlError>

Source

pub fn check_remote_metadata( &self, remote_agent: &str, descs: Option<&XferDescList<'_>>, ) -> bool

Check if remote metadata for a specific agent is available

This function checks if the metadata for the specified remote agent has been loaded and if specific descriptors can be found in the metadata.

§Arguments

remote_agent - Name of the remote agent to check
descs - Optional descriptor list to check against the remote metadata. If None, only checks if any metadata exists for the agent.

§Returns

true if the remote agent’s metadata is available (and descriptors are found if provided), false otherwise

Source

pub fn invalidate_remote_md(&self, remote_agent: &str) -> Result<(), NixlError>

Invalidates a remote metadata for this agent

Source

pub fn invalidate_all_remotes(&self) -> Result<(), NixlError>

Invalidates all remote metadata for this agent

Source

pub fn send_local_md(&self, opt_args: Option<&OptArgs>) -> Result<(), NixlError>

Send this agent’s metadata to etcdAdd commentMore actions

This enables other agents to discover this agent’s metadata via etcd.

§Arguments

opt_args - Optional arguments for sending metadata

Source

pub fn send_local_partial_md( &self, descs: &RegDescList<'_>, opt_args: Option<&OptArgs>, ) -> Result<(), NixlError>

Send this agent’s partial metadata

§Arguments

descs - Registration descriptor list to send
opt_args - Optional arguments for sending metadata

Source

pub fn fetch_remote_md( &self, remote_name: &str, opt_args: Option<&OptArgs>, ) -> Result<(), NixlError>

Fetch a remote agent’s metadata from etcd

Once fetched, the metadata will be loaded and cached locally, enabling communication with the remote agent.

§Arguments

remote_name - Name of the remote agent to fetch metadata for
opt_args - Optional arguments for fetching metadata

Source

pub fn invalidate_local_md( &self, opt_args: Option<&OptArgs>, ) -> Result<(), NixlError>

Invalidate this agent’s metadata in etcd

This signals to other agents that this agent’s metadata is no longer valid.

§Arguments

opt_args - Optional arguments for invalidating metadata

Source

pub fn send_notification( &self, remote_agent: &str, message: &[u8], backend: Option<&Backend>, ) -> Result<(), NixlError>

Send a notification to a remote agent

§Arguments

remote_agent - Name of the remote agent to send notification to
message - The notification message to send
backend - Optional backend to use for sending the notification

§Returns

Ok(()) if the notification was sent successfully

Source

pub fn create_xfer_req( &self, operation: XferOp, local_descs: &XferDescList<'_>, remote_descs: &XferDescList<'_>, remote_agent: &str, opt_args: Option<&OptArgs>, ) -> Result<XferRequest, NixlError>

Creates a transfer request between local and remote descriptors

§Arguments

operation - The transfer operation (read or write)
local_descs - The local descriptor list
remote_descs - The remote descriptor list
remote_agent - The name of the remote agent
opt_args - Optional arguments for the transfer

§Returns

A handle to the transfer request

§Errors

Returns a NixlError if the operation fails

Source

pub fn estimate_xfer_cost( &self, req: &XferRequest, opt_args: Option<&OptArgs>, ) -> Result<(i64, i64, CostMethod), NixlError>

Estimates the cost of a transfer request

§Arguments

req - Transfer request handle
opt_args - Optional arguments for the estimation

§Returns

A tuple containing (duration in microseconds, error margin in microseconds, cost method)

§Errors

Returns a NixlError if the operation fails

Source

pub fn post_xfer_req( &self, req: &XferRequest, opt_args: Option<&OptArgs>, ) -> Result<bool, NixlError>

Posts a transfer request to initiate a transfer

After this, the transfer state can be checked asynchronously until completion. For small transfers that complete within the call, the function returns Ok(false). Otherwise, it returns Ok(true) to indicate the transfer is in progress.