Struct RemoteMemoryRegion

Source

pub struct RemoteMemoryRegion { /* private fields */ }

Expand description

A handle to a memory region on a remote peer.

This struct provides the necessary coordinates (Address, Length, RKey) to perform One-Sided RDMA operations (Read/Write) against a remote node.

§The “Contiguous” Constraint

Unlike local operations which support Scatter/Gather (stitching fragmented memory together), remote operations are strictly contiguous.

Targeting — You specify a single starting address and a total length.
Behavior — The RDMA hardware reads or writes a continuous stream of bytes starting at that virtual address.

If you need to write to multiple non-contiguous buffers on a remote peer, you must issue multiple distinct RDMA Write operations.

§Safety and Responsibility

As discussed in the memory module, remote memory safety cannot be enforced by the Rust compiler.

Local Safety — Safe. Even if this handle points to invalid memory, issuing an operation using it will only result in an error (or success), but will never corrupt local process memory.
Remote Safety — Unsafe. If you write to a RemoteMemoryRegion that has been deallocated on the remote peer, the remote NIC will unknowingly overwrite that memory. This causes Undefined Behavior on the remote peer.

Implementations§

Source §

impl RemoteMemoryRegion

Source

pub fn new(addr: u64, length: usize, rkey: u32) -> Self

Creates a new RemoteMemoryRegion from its raw components.

This is typically done after receiving these values from a remote peer via an out-of-band communication channel (like a TCP socket or UD message).

Source

pub fn address(&self) -> u64

Returns the starting virtual address of the remote memory.

Source

pub fn length(&self) -> usize

Returns the length of the remote memory region.

Note: This value is stored for client-side bounds checking and convenience. The actual hardware enforcement depends on how the memory was registered on the remote peer.

Source

pub fn rkey(&self) -> u32

Returns the Remote Key (rkey) authorizing access to this memory.

Source

pub fn sub_region(&self, offset: usize) -> Option<RemoteMemoryRegion>

Creates a generic sub-region derived from this one.

This acts as a handle to a specific slice of the remote memory, starting at offset bytes from the base address.

§Returns

Some(RemoteMemoryRegion) — If offset <= self.length. The new length is self.length - offset.
None — If offset > self.length.

Source

pub fn sub_region_unchecked(&self, offset: usize) -> RemoteMemoryRegion

Same as sub_region but without client-side bounds checking.

§Safety

This is safe from a Rust memory model perspective locally. If the calculated address/length falls outside the actual bounds registered on the remote peer, the RDMA hardware will reject the operation with a Remote Access Error.