Struct ResourceHandle 

pub struct ResourceHandle { /* private fields */ }

RAII wrapper around cugraph_resource_handle_t.

Manages GPU resources (CUDA stream and the underlying cuGraph resource handle). Automatically freed on drop (unless created via from_raw_resource_handle, which borrows an external cuGraph resource handle). Not thread-safe; must be used from the thread that created it.

Implementations

impl ResourceHandle

pub fn for_runtime(runtime: Arc<Runtime>) -> Result<Self>

Create a new resource handle bound to a cudf runtime owner.

This constructor binds cuGraph to the runtime’s CUDA stream and RAFT workspace/resource-aware allocation context through a local native shim that owns both the RAFT handle and the cuGraph resource-handle wrapper. All handles for the same exact runtime stream/MR binding share one shim.

pub unsafe fn from_raw_resource_handle( raw: *mut cugraph_resource_handle_t, ) -> Result<Self>

Wrap an existing cuGraph resource handle created externally.

This constructor is intended for multi-GPU workflows where a per-thread cugraph_resource_handle_t* has already been created externally (for example by an MTMG or MPI-aware native layer). The returned wrapper does not own the handle; it will not be freed on drop. The wrapped handle is assumed to belong to the calling thread’s current CUDA device at the moment this function is called.

Safety

The caller must ensure:

• raw is a valid, non-null pointer to a cugraph_resource_handle_t created by cuGraph-compatible native code
• the calling thread’s current CUDA device is the device that raw is bound to
• the handle remains valid for the lifetime of this ResourceHandle
• the handle is not freed externally while this wrapper exists
• the calling thread obeys the external runtime’s thread-affinity rules
• graph operations run through this handle bypass Graph::park ordering, making the graph ineligible for parked transfer

pub unsafe fn adopt_raw_resource_handle( raw: *mut cugraph_resource_handle_t, ) -> Result<Self>

Adopt ownership of an existing cuGraph resource handle created externally.

This constructor is intended for native MTMG or MPI-aware shims that allocate a fresh cugraph_resource_handle_t* for Rust and transfer destruction responsibility to Rust. The returned wrapper owns the handle and will free it on drop using cugraph_free_resource_handle. The adopted handle is assumed to belong to the calling thread’s current CUDA device at the moment this function is called.

Safety

The caller must ensure:

• raw is a valid, non-null pointer to a cugraph_resource_handle_t
• ownership of raw is transferred exactly once to this wrapper
• no other owner will free raw after this call succeeds
• the calling thread’s current CUDA device is the device that raw is bound to
• the calling thread obeys the external runtime’s thread-affinity rules
• graph operations run through this handle bypass Graph::park ordering, making the graph ineligible for parked transfer

For a borrowed/non-owning wrapper, use from_raw_resource_handle instead.

pub fn into_raw_resource_handle(self) -> Result<*mut cugraph_resource_handle_t>

Consume this wrapper and return the underlying raw handle pointer.

Suppresses Rust-side Drop. Automatic cugraph_free_resource_handle teardown does not occur.

Ownership semantics are preserved from the source wrapper:

• if self owned the handle, the caller becomes responsible for freeing it according to the cuGraph resource-handle ownership contract
• if self only borrowed the handle, the caller still does not own it and must follow the original external destruction contract

Runtime-bound handles cannot be converted into standalone raw resource handles because the native shim must continue to own the paired RAFT handle and destroy both objects together.

pub fn device(&self) -> i32

The CUDA device this handle was created on.

pub fn runtime(&self) -> Option<&Runtime>

pub fn rank(&self) -> i32

The communicator rank carried by this handle.

Handles created through for_runtime always return 0.

Externally wrapped handles query cuGraph’s communicator metadata and are intended for MTMG/MG-native handles that already carry a valid communicator.

pub fn comm_size(&self) -> i32

The communicator size carried by this handle.

Handles created through for_runtime always return 1.

Externally wrapped handles query cuGraph’s communicator metadata and are intended for MTMG/MG-native handles that already carry a valid communicator.

pub fn enter(&self, operation: &'static str) -> Result<EnteredContext<'_>>

Enter the owner device on the current thread and create an execution session for GPU-capable work. Runtime-bound handles serialize entry for the shared native owner; nested same-owner entry on one thread returns an error immediately without deadlocking.

Trait Implementations

impl Debug for ResourceHandle

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

Formats the value using the given formatter.

impl Drop for ResourceHandle

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.