Struct ScatterElement 

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

A Scatter Element for incoming RDMA operations.

Purpose

A ScatterElement represents a slice of registered memory that the NIC will write into when receiving from the network. The NIC “scatters” the incoming stream across a list of these elements.

Usage

Use this for operations where the local node receives data:

• Receive Requests — The buffer to fill with incoming data.
• RDMA Read — The local destination buffer.

Safety and Lifetimes

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

• Exclusive Access — It holds a &'a mut [u8] to the data, ensuring no other part of the program can read or write this memory while the NIC is writing to it.
• 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

impl<'a> ScatterElement<'a>

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

Creates a new scatter 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:

1. The data slice is fully contained within the mr’s address range.
2. 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.

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

Creates a new Scatter Element with bounds checking.

Checks

This method validates that:

1. The data slice is fully contained within the mr’s address range.
2. The data length fits in a u32.

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

Creates a new Scatter 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.

Trait Implementations

impl<'a> Debug for ScatterElement<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.