Struct GatherElement

Source

pub struct GatherElement<'a> { /* private fields */ }

Expand description

A Gather Element for outgoing RDMA operations.

§Purpose

A GatherElement represents a slice of registered memory that the NIC will read from to send over the network. The NIC “gathers” data from a list of these elements into a single continuous stream.

§Usage

Use this for operations where the local node sends data:

Send Requests — The payload to send.
RDMA Write — The local source buffer.

§Safety and Lifetimes

This struct enforces Rust’s borrowing rules at the hardware level:

Immutable Access — It holds a &'a [u8] to the data, allowing shared access but preventing mutation while the operation is pending.
Liveness — It holds a reference to the MemoryRegion, ensuring the registration remains valid.

See the memory module for a detailed explanation of the safety architecture.

Implementations§

Source §

impl<'a> GatherElement<'a>

Source

pub fn new(mr: &'a MemoryRegion, data: &'a [u8]) -> Self

Creates a new gather element.

In debug builds, this performs additional validation before constructing the element. In optimized/release builds, these validations are not executed by default because they are implemented using debug_assert!.

§Panics

Panics in debug builds if any of the following conditions are violated:

The data slice is fully contained within the mr’s address range.
The data length fits in a u32 (hardware limit).

For a version that always validates and returns an error instead of panicking, use Self::new_checked.

Source

pub fn new_checked( mr: &'a MemoryRegion, data: &'a [u8], ) -> Result<Self, ScatterGatherElementError>

Creates a new Gather Element with bounds checking.

§Checks

This method validates that:

The data slice is fully contained within the mr’s address range.
The data length fits in a u32 (hardware limit).

Source

pub fn new_unchecked(mr: &'a MemoryRegion, data: &'a [u8]) -> Self

Creates a new Gather Element without bounds checking.

§Safety

This method is safe to call from a Rust memory-safety perspective. If the slice is outside the MR, the hardware will detect this during RDMA operations and fail with a Local Protection Error.

§Warning

If data.len() exceeds u32::MAX, the length stored in the SGE will silently wrap. Only the wrapped (truncated) number of bytes will be posted to the hardware. Use new_checked to catch this at the cost of a bounds check.