Struct KeepaliveLocalMemory 

pub struct KeepaliveLocalMemory { /* private fields */ }

Local memory handle that keeps its backing allocation alive via an Arc<dyn Keepalive>.

Detects at construction time whether the address is a CUDA device pointer and dispatches read_at/write_at accordingly.

All three access methods are unsafe: the Keepalive only guarantees the allocation stays mapped, not that this handle has unique ownership. The internal [AccessLock] coordinates concurrent callers that share the same clone of this handle (readers run in parallel, exclusive writers run alone, disjoint writers run in parallel with one another but exclude readers and exclusive writers), but callers must additionally rule out concurrent access through other views of the same allocation.

The direct_access_host_bandwidth and direct_access_device_bandwidth fields indicate the speed of reading the memory via pointer dereference on a host or device thread, respectively. A value of None means the memory is not directly accessible from that context.

Implementations

impl KeepaliveLocalMemory

pub fn try_new(keepalive: Arc<dyn Keepalive>) -> Result<Self, Error>

Try to create a new handle. Derives addr and size from the keepalive via Keepalive::addr / Keepalive::size, then resolves the region’s MemoryLocation and sets the bandwidth fields accordingly.

Errors when the location cannot be resolved.

pub fn addr(&self) -> usize

Starting virtual address of the memory region.

pub fn size(&self) -> usize

Size of the memory region in bytes.

pub fn location(&self) -> MemoryLocation

Where this region lives.

pub fn registered_mr<I: IbvDeviceImpl>( &self, device: &str, ) -> Result<Option<IbvMemoryRegionView>, Error>

This handle’s registration of the region on backend I’s device, if it has one.

Err means a previous attempt to register on device failed and carries that error; the caller should not retry. Ok(None) means this handle has never registered there.

The registrations are shared by Arc across clones of this handle, and with any WeakLocalMemory downgraded from it, so one clone’s registration is visible to all of them. Handles built separately over the same region share nothing.

pub fn registered_mrs<I: IbvDeviceImpl>(&self) -> Vec<IbvMemoryRegionView>

Every registration this handle has on a device of backend I.

pub fn install_mr<I: IbvDeviceImpl>( &self, view: IbvMemoryRegionView, ) -> Result<IbvMemoryRegionView, Error>

Record view as this handle’s registration on backend I’s view.device_name and return the registration now in force there.

Idempotent: a registration already present wins, and view is dropped (deregistering it, since nothing else holds it).

Errors when the device already carries a recorded failure, which two callers registering the same region on the same device at once can reach: one fails and records it, the other succeeds and arrives here. The recorded failure stands and view is dropped, so the region keeps answering with the failure rather than flip-flopping on who got there last.

pub fn record_mr_failure<I: IbvDeviceImpl>(&self, device: &str, error: &Error)

Record that registering this region on backend I’s device failed, so later transfers see the failure instead of retrying it. A registration already in force on device wins: one caller’s failure does not invalidate another’s working keys.

pub unsafe fn read_at(&self, offset: usize, dst: &mut [u8]) -> Result<(), Error>

Copy dst.len() bytes from this memory region starting at offset into dst.

Mutually exclusive with both write_at and write_at_disjoint across clones of this handle: the [AccessLock] guarantees a reader and any writer (exclusive or disjoint) that share the same lock never observe each other’s partial state. Multiple concurrent read_at calls on shared clones are permitted and run in parallel.

Safety

The Keepalive guarantees the allocation stays mapped, but it does not imply unique ownership: another component may hold its own view of the same allocation and read or write it concurrently outside this handle’s [AccessLock]. The caller must ensure that no such external access produces a torn read of offset..offset + dst.len() for the duration of this call.

pub unsafe fn write_at(&self, offset: usize, src: &[u8]) -> Result<(), Error>

Copy src.len() bytes from src into this memory region starting at offset.

Mutually exclusive with every other read and write against this region across clones of this handle: the [AccessLock] blocks concurrent readers and writers that share the same lock. Use KeepaliveLocalMemory::write_at_disjoint when multiple writers can be proven to target disjoint byte ranges.

Safety

See KeepaliveLocalMemory::read_at. The Keepalive guarantee covers liveness only; the caller must ensure no concurrent external reader or writer observes an overlapping byte range.

pub unsafe fn write_at_disjoint( &self, offset: usize, src: &[u8], ) -> Result<(), Error>

Like KeepaliveLocalMemory::write_at, but allows other concurrent write_at_disjoint calls (across clones of this handle) to proceed in parallel. Still mutually exclusive with read_at and write_at through the [AccessLock].

Safety

In addition to the obligations of KeepaliveLocalMemory::write_at (no external concurrent reader or writer of the same byte range), the caller must ensure that no other concurrent call to this method targets a byte range that overlaps offset..offset + src.len(). Disjoint byte ranges across concurrent disjoint callers are sound.

pub fn downgrade(&self) -> Option<WeakLocalMemory>

Pair off a WeakLocalMemory that shares this handle’s [LocalMemoryInner] (and therefore the same registrations and access lock). Returns None when the underlying Keepalive does not provide a weak form.

Trait Implementations

impl Clone for KeepaliveLocalMemory

fn clone(&self) -> KeepaliveLocalMemory

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for KeepaliveLocalMemory

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

Formats the value using the given formatter.