Struct Session 

pub struct Session<'s> { /* private fields */ }

Raw CUDA extension session.

Not constructible by users. Represents “tenferro primary context active on this thread with one captured execution stream bound”. !Send + !Sync by construction (Rc).

Implementations

impl<'s> Session<'s>

pub fn runtime_identity(&self) -> CudaRuntimeIdentity

Return the identity of the runtime backing this session.

pub fn synchronize(&self) -> Result<()>

Block the host until work enqueued on the session’s stream completes.

This is the only host barrier on the raw-session success path; regular successes only enqueue.

Errors

Returns crate::Error::BackendSource when the CUDA synchronize call fails.

pub fn stream(&self) -> StreamRef<'s>

Borrow the captured execution stream.

pub fn tensor<'a, T>( &'a self, tensor: &'a TypedTensor<T, impl TensorRank>, ) -> Result<TensorRef<'a, T>>

where T: 'static,

Build a checked read-only device reference for a GPU-backed tensor.

The returned reference is tied to both this session borrow and the tensor borrow, so the span cannot outlive the tensor’s allocation.

Errors

Returns crate::Error::RuntimeState when the tensor is not resident on this session’s runtime/device.

pub fn tensor_mut<'a, T>( &'a self, tensor: &'a mut TypedTensor<T, impl TensorRank>, ) -> Result<TensorMut<'a, T>>

where T: 'static,

Build a checked mutable device reference for a GPU-backed tensor.

Requires an exclusive borrow of the tensor, so aliasing mutable device access cannot be produced from a shared &TypedTensor<T>. The returned reference is tied to both this session borrow and the tensor borrow, so the span cannot outlive the tensor’s allocation.

Errors

Returns crate::Error::RuntimeState when the tensor is not resident on this session’s runtime/device.

pub fn alloc_output<T>(&self, shape: &[usize]) -> Result<TypedTensor<T>>

where T: CubeElement + TensorScalar + Clone + Send + Sync + 'static,

Allocate a dense GPU tensor of T on the session’s device.

Errors

Returns crate::Error::Validation on shape overflow or crate::Error::BackendSource on allocation failure.

pub fn retain_tensor<T>( &self, tensor: &TypedTensor<T, impl TensorRank>, op: &'static str, ) -> Result<DeviceBytes<'s>>

where T: 'static,

Retain a clone of a resident tensor’s CubeCL allocation handle.

The returned DeviceBytes holds a reference-counted clone of the tensor’s allocation handle, so the device memory stays alive until the guard is dropped. Use this when a vendor library enqueues asynchronous work against the tensor’s address and, on a failed synchronization barrier, the guard must be intentionally forgotten so allocation reclamation cannot race an in-flight kernel.

Errors

Returns crate::Error::RuntimeState when tensor is host-backed, belongs to a non-CubeCL backend family, belongs to a different CUDA runtime domain, or is not resident on this session’s device, or crate::Error::BackendSource when CubeCL cannot inspect the retained resource.

Examples

use tenferro_gpu::cuda::raw::{DeviceBytes, Session};
use tenferro_tensor::TypedTensor;

fn check<'s>(
    raw: &Session<'s>,
    tensor: &TypedTensor<f32>,
) -> tenferro_tensor::Result<DeviceBytes<'s>> {
    raw.retain_tensor(tensor, "test.retain_tensor")
}

pub fn alloc_bytes( &self, nbytes: usize, op: &'static str, ) -> Result<DeviceBytes<'s>>

Allocate a CubeCL-owned byte workspace returned as DeviceBytes.

Errors

Returns crate::Error::BackendSource when CubeCL cannot allocate or inspect the workspace resource.

pub unsafe fn copy_bytes( &self, dst: *mut c_void, src: *const c_void, nbytes: usize, op: &'static str, ) -> Result<()>

Copy bytes from one device span to another on the session stream.

Both spans must be produced by this session (via Session::tensor, Session::tensor_mut, or Session::alloc_bytes) and must not overlap; the copy is stream-ordered with other enqueued work. This is the raw equivalent of a same-device memcpyDeviceToDeviceAsync.

Safety

dst and src must be aligned device spans of at least nbytes bytes, backed by allocations that outlive the (unsynchronized) copy; dst must be uniquely owned for writing and src must not alias it.

Errors

Returns crate::Error::BackendSource when the driver rejects the device-to-device copy.

pub fn upload_bytes( &self, bytes: &[u8], op: &'static str, ) -> Result<DeviceBytes<'s>>

Upload host bytes into a CubeCL-owned workspace returned as DeviceBytes.

Errors

Returns crate::Error::BackendSource when CubeCL cannot upload or inspect the workspace resource, or crate::Error::Validation when the pointer address cannot be represented as usize.

pub fn download_tensor<T>( &self, tensor: &TypedTensor<T, impl TensorRank>, op: &'static str, ) -> Result<TypedTensor<T>>

where T: CubeElement + TensorScalar + Clone + Send + Sync + 'static,

Read a resident tensor’s bytes back to host memory.

Synchronizes the session stream, then returns the tensor data as a host-resident typed tensor (same shape). This is the only host barrier introduced by the raw-session path; call it only where a value must be inspected or returned to the host.

Errors

Returns crate::Error::RuntimeState when the tensor is not resident on this session’s runtime/device, or crate::Error::BackendSource when synchronization or readback fails.

pub fn load_ptx(&self, ptx: &CStr) -> Result<Module>

Load a CUDA module from PTX source text.

The PTX is compiled for the current device’s architecture by the driver; on older toolchains pass PTX compiled with a compatible compute_XX target. The raw session context is current, so no explicit context switch is needed.

Errors

Returns crate::Error::BackendSource when the driver rejects the image (unsupported format, architecture mismatch).

pub fn load_cubin(&self, cubin: &[u8]) -> Result<Module>

Load a CUDA module from CUBIN binary data.

CUBIN is architecture-specific; it must have been compiled for the current device.

Errors

Returns crate::Error::BackendSource when the driver rejects the image (mismatched architecture, corrupt data).

pub fn compile_nvrtc(&self, src: &str, opts: &NvrtcOptions) -> Result<Module>

Compile CUDA source to PTX on the host using NVRTC, then load it.

The resulting module is loaded on the session’s primary context.

Errors

Returns crate::Error::BackendSource when NVRTC compilation or the driver load fails, or crate::Error::Validation when the source contains a NUL byte.

pub unsafe fn launch( &self, function: &Function, config: LaunchConfig, args: &[KernelArg<'_>], ) -> Result<()>

Launch a raw CUDA kernel on the session’s captured stream.

The kernel is enqueued, not synchronized; call Session::synchronize for a host barrier.

Safety

The caller must guarantee all of the following for the duration of the launch and until the work is synchronized:

• ABI/arguments: every KernelArg matches the kernel’s formal parameter list in order (scalars of the exact width/type, device pointers exactly where the kernel expects them). TensorRef args that the kernel writes must be passed as the mutable form.
• Read/write ranges: the kernel only reads/writes within the span validated by the tensor’s TensorRef/TensorMut and only where the launch geometry covers; out-of-bounds access is UB.
• Aliasing: no two args alias the same device memory unless the kernel contract permits it.
• Liveness: every referenced device allocation and the Module (via its Function) outlive the asynchronous work; the caller must not drop the tensors or module until after a subsequent Session::synchronize.

Errors

Returns crate::Error::Validation carrying ValidationError::InvalidArgument when the launch geometry or limits are invalid, or crate::Error::BackendSource when the driver rejects the launch.

pub fn resource<T>( &self, init: impl FnOnce() -> Result<T>, ) -> Result<CudaResourceGuard<'_, T>>

where T: Send + 'static,

Get or lazily initialize a runtime-scoped, type-keyed extension resource.

This is the narrow public view over the existing bounded per-runtime CudaExtensionCache. The guard holds the cache lock and serializes access; cache keys remain per exact runtime instance (never per-device).

Errors

Returns the initializer’s typed error, or crate::Error::RuntimeState when the extension cache is poisoned.