Struct CudaExecSession 

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

Borrowed CUDA execution capability.

This is the single public execution-authority boundary for CUDA kernel extensions (issue #1597). External operation crates obtain it through with_cuda_exec_session and then borrow backend/device-scoped extension sessions via CudaExecSession::with_cubecl and CudaExecSession::with_raw.

The session is not constructible by users and is !Send + !Sync: it carries thread-local execution capability. Success of an enrolled operation means the work was enqueued; only CudaExecSession::synchronize is a host barrier.

Implementations

impl CudaExecSession<'_>

pub fn runtime(&self) -> &CudaRuntime

Borrow the provider runtime without exposing the backend.

pub fn runtime_identity(&self) -> CudaRuntimeIdentity

Return the identity of the borrowed provider runtime.

pub fn supports(&self, capability: GpuExtensionCapability) -> bool

Report whether this session supports a GPU extension capability.

Examples

use tenferro_gpu::cuda::{CudaExecSession, GpuExtensionCapability};

// Method-call check only: `CudaExecSession` is not user-constructible, so
// the example asserts the method is callable from an external crate.
fn check(session: &CudaExecSession<'_>, capability: GpuExtensionCapability) -> bool {
    session.supports(capability)
}
let _ = check;

pub fn device_info(&self) -> &CudaDeviceInfo

Borrow immutable metadata for the session’s device.

Examples

use tenferro_gpu::cuda::CudaExecSession;

// Method-call check only: `CudaExecSession` is not user-constructible, so
// the example asserts the method is callable from an external crate.
fn check(session: &CudaExecSession<'_>) {
    let _ = session.device_info();
}
let _ = check;

pub fn allocation_domain(&self) -> AllocationDomainId

Return the allocation ownership domain of this session.

Examples

use tenferro_gpu::cuda::CudaExecSession;

// Method-call check only: `CudaExecSession` is not user-constructible, so
// the example asserts the method is callable from an external crate.
fn check(session: &CudaExecSession<'_>) -> tenferro_tensor::AllocationDomainId {
    session.allocation_domain()
}
let _ = check;

pub fn ensure_gpu_resident( &self, input: &Tensor, op: &'static str, ) -> Result<()>

Validate that a dense GPU tensor is resident on this exact session: CubeCL-backed, same allocation domain, and placed on this runtime’s CUDA device. Rejects host tensors, foreign-backend buffers, and foreign-runtime/device tensors without an implicit transfer.

This is the credentialed public-seam residency guard for extension crates that receive a session but must validate inputs before entering a with_raw/with_cubecl sub-session.

Errors

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

Examples

use tenferro_gpu::cuda::CudaExecSession;

// Method-call check only: `CudaExecSession` is not user-constructible.
fn check(session: &CudaExecSession<'_>, tensor: &tenferro_tensor::Tensor) -> tenferro_tensor::Result<()> {
    session.ensure_gpu_resident(tensor, "test.ensure_gpu_resident")
}
let _ = check;

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

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

This is the only host barrier on the success path; ordinary successful session operations only enqueue.

Errors

Returns crate::Error::BackendSource when CUDA stream synchronization fails.

pub fn with_raw<R>( &mut self, op: &'static str, f: impl for<'s> FnOnce(&mut Session<'s>) -> Result<R>, ) -> Result<R>

Borrow the type-safe raw CUDA extension session for one operation.

The enter/exit protocol is fully contained in this call: a definite CubeCL stream is captured on the current thread, pending CubeCL work is flushed, the calling thread’s previous device/context is saved, the tenferro primary context is activated, the callback runs, and the previous device/context is best-effort restored on return, Err, or unwind (restoration failures are logged to stderr). The success path does not synchronize.

Errors

Returns crate::Error::BackendSource when CubeCL cannot expose or flush the stream, or when the CUDA context cannot be entered. Context restoration on exit is best-effort: a failure to restore the caller’s previous device/context is logged to stderr rather than propagated, so a callback result is never replaced by a restore error.

Examples

use tenferro_gpu::cuda::CudaExecSession;

// Method-call check only: `CudaExecSession` is not user-constructible.
fn check(session: &mut CudaExecSession<'_>) -> tenferro_tensor::Result<()> {
    session.with_raw("test.raw", |raw| {
        let _ = raw.stream();
        Ok(SessionOutcome::Done)
    })?;
    Ok(())
}
enum SessionOutcome { Done }
let _ = check;

pub fn with_cubecl<R>( &mut self, op: &'static str, f: impl for<'s> FnOnce(&Session<'s>) -> Result<R>, ) -> Result<R>

Borrow the public tenferro-wide CubeCL session for one operation.

The session exposes the exact tenferro CubeCL client bound to this runtime. Pending CubeCL work is flushed before entering and again on exit (including Err and unwind) so a later raw-session or host read observes the enqueued work. The success path does not synchronize.

Examples

use tenferro_gpu::cuda::CudaExecSession;

fn check(session: &mut CudaExecSession<'_>) {
    let _ = session.with_cubecl("test.cubecl", |_cubecl| Ok(()));
}
let _ = check;

Errors

Returns the callback’s error, or crate::Error::BackendSource when pending CubeCL work cannot be flushed on entry or exit.

Trait Implementations

impl BackendSession for CudaExecSession<'_>

fn vdot_read( &mut self, _lhs: TensorRead<'_>, _rhs: TensorRead<'_>, ) -> Result<Tensor, Error>

Compute the all-axis conjugating dot product without transferring either input.

fn norm_squared_read(&mut self, _input: TensorRead<'_>) -> Result<Tensor, Error>

Compute the all-axis sum of squared magnitudes without taking a square root.

fn axpby_read_into_accum( &mut self, _alpha: ContractionScalar, _x: TensorRead<'_>, _beta: ContractionScalar, _y: TensorWrite<'_>, ) -> Result<(), Error>

Apply y <- alpha * x + beta * y in one pass into caller-owned storage.

impl<'a> Debug for CudaExecSession<'a>

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

Formats the value using the given formatter.

impl SessionCachedDot for CudaExecSession<'_>

fn dot_general_read_into_accum_cached( &mut self, cache_slot: Option<usize>, lhs: TensorRead<'_>, rhs: TensorRead<'_>, config: &DotGeneralConfig, accumulation: DotGeneralAccumulation, out: TensorWrite<'_>, ) -> Result<()>

Apply session-cached scaled dot-general accumulation into output.

impl TensorAnalytic for CudaExecSession<'_>

fn exp(&mut self, input: &Tensor) -> Result<Tensor>

Errors

fn log(&mut self, input: &Tensor) -> Result<Tensor>

Errors

fn sin(&mut self, input: &Tensor) -> Result<Tensor>

Errors

fn cos(&mut self, input: &Tensor) -> Result<Tensor>

Errors

fn tanh(&mut self, input: &Tensor) -> Result<Tensor>

Errors

fn sqrt(&mut self, input: &Tensor) -> Result<Tensor>

Errors

fn rsqrt(&mut self, input: &Tensor) -> Result<Tensor>

Errors

fn pow(&mut self, lhs: &Tensor, rhs: &Tensor) -> Result<Tensor>

Errors

fn expm1(&mut self, input: &Tensor) -> Result<Tensor>

Errors

fn log1p(&mut self, input: &Tensor) -> Result<Tensor>

Errors

fn exp_read(&mut self, input: TensorRead<'_>) -> Result<Tensor, Error>

Errors

fn log_read(&mut self, input: TensorRead<'_>) -> Result<Tensor, Error>

Errors

fn sin_read(&mut self, input: TensorRead<'_>) -> Result<Tensor, Error>

Errors

fn cos_read(&mut self, input: TensorRead<'_>) -> Result<Tensor, Error>

Errors

fn tanh_read(&mut self, input: TensorRead<'_>) -> Result<Tensor, Error>

Errors

fn sqrt_read(&mut self, input: TensorRead<'_>) -> Result<Tensor, Error>

Errors

fn rsqrt_read(&mut self, input: TensorRead<'_>) -> Result<Tensor, Error>

Errors

fn pow_read( &mut self, lhs: TensorRead<'_>, rhs: TensorRead<'_>, ) -> Result<Tensor, Error>

Errors

fn expm1_read(&mut self, input: TensorRead<'_>) -> Result<Tensor, Error>

Errors

fn log1p_read(&mut self, input: TensorRead<'_>) -> Result<Tensor, Error>

Errors

impl TensorBuffer for CudaExecSession<'_>

fn reclaim_buffer(&mut self, tensor: Tensor)

impl TensorDeviceTransfer for CudaExecSession<'_>

fn download_to_host(&mut self, tensor: TensorRead<'_>) -> Result<Tensor>

Explicitly copy a provider-owned read target into host storage.

fn upload_host_tensor(&mut self, tensor: TensorRead<'_>) -> Result<Tensor>

Explicitly copy a host read target into provider storage.

impl TensorDot for CudaExecSession<'_>

fn dot_general( &mut self, lhs: &Tensor, rhs: &Tensor, config: &DotGeneralConfig, ) -> Result<Tensor>

Errors

fn dot_general_read_into_accum( &mut self, lhs: TensorRead<'_>, rhs: TensorRead<'_>, config: &DotGeneralConfig, accumulation: DotGeneralAccumulation, out: TensorWrite<'_>, ) -> Result<()>

Apply scaled dot-general accumulation into caller-provided output.

fn dot_general_read_into( &mut self, lhs: TensorRead<'_>, rhs: TensorRead<'_>, config: &DotGeneralConfig, out: TensorWrite<'_>, ) -> Result<(), Error>

Overwrite caller-provided output with dot-general from read inputs.

impl TensorElementwise for CudaExecSession<'_>

fn add(&mut self, lhs: &Tensor, rhs: &Tensor) -> Result<Tensor>

Errors

fn sub(&mut self, lhs: &Tensor, rhs: &Tensor) -> Result<Tensor>

Errors

fn mul(&mut self, lhs: &Tensor, rhs: &Tensor) -> Result<Tensor>

Errors

fn neg(&mut self, input: &Tensor) -> Result<Tensor>

Errors

fn conj(&mut self, input: &Tensor) -> Result<Tensor>

Errors

fn div(&mut self, lhs: &Tensor, rhs: &Tensor) -> Result<Tensor>

Errors

fn rem(&mut self, lhs: &Tensor, rhs: &Tensor) -> Result<Tensor>

Elementwise remainder.

fn abs(&mut self, input: &Tensor) -> Result<Tensor>

Errors

fn sign(&mut self, input: &Tensor) -> Result<Tensor>

Errors

fn maximum(&mut self, lhs: &Tensor, rhs: &Tensor) -> Result<Tensor>

Errors

fn minimum(&mut self, lhs: &Tensor, rhs: &Tensor) -> Result<Tensor>

Errors

fn compare( &mut self, lhs: &Tensor, rhs: &Tensor, dir: &CompareDir, ) -> Result<Tensor>

Errors

fn select( &mut self, pred: &Tensor, on_true: &Tensor, on_false: &Tensor, ) -> Result<Tensor>

Errors

fn clamp( &mut self, input: &Tensor, lower: &Tensor, upper: &Tensor, ) -> Result<Tensor>

Errors

fn elementwise_read_into( &mut self, op: ElementwiseReadOp, inputs: &[TensorRead<'_>], out: TensorWrite<'_>, ) -> Result<(), Error>

Execute an elementwise operation into caller-owned storage.

fn add_read( &mut self, lhs: TensorRead<'_>, rhs: TensorRead<'_>, ) -> Result<Tensor, Error>

Elementwise addition accepting either owned tensors or borrowed views.

fn add_into( &mut self, lhs: &Tensor, rhs: &Tensor, out: TensorWrite<'_>, ) -> Result<(), Error>

Overwrite caller-provided output with elementwise addition.

fn add_read_into( &mut self, lhs: TensorRead<'_>, rhs: TensorRead<'_>, out: TensorWrite<'_>, ) -> Result<(), Error>

Overwrite caller-provided output with elementwise addition from reads.

fn sub_read( &mut self, lhs: TensorRead<'_>, rhs: TensorRead<'_>, ) -> Result<Tensor, Error>

Elementwise subtraction accepting either owned tensors or borrowed views.

fn sub_into( &mut self, lhs: &Tensor, rhs: &Tensor, out: TensorWrite<'_>, ) -> Result<(), Error>

Overwrite caller-provided output with elementwise subtraction.

fn sub_read_into( &mut self, lhs: TensorRead<'_>, rhs: TensorRead<'_>, out: TensorWrite<'_>, ) -> Result<(), Error>

Overwrite caller-provided output with elementwise subtraction from reads.

fn mul_read( &mut self, lhs: TensorRead<'_>, rhs: TensorRead<'_>, ) -> Result<Tensor, Error>

Errors

fn mul_into( &mut self, lhs: &Tensor, rhs: &Tensor, out: TensorWrite<'_>, ) -> Result<(), Error>

Overwrite caller-provided output with elementwise multiplication.

fn mul_read_into( &mut self, lhs: TensorRead<'_>, rhs: TensorRead<'_>, out: TensorWrite<'_>, ) -> Result<(), Error>

Overwrite caller-provided output with elementwise multiplication from reads.

fn neg_read(&mut self, input: TensorRead<'_>) -> Result<Tensor, Error>

Errors

fn neg_into( &mut self, input: &Tensor, out: TensorWrite<'_>, ) -> Result<(), Error>

Overwrite caller-provided output with elementwise negation.

fn neg_read_into( &mut self, input: TensorRead<'_>, out: TensorWrite<'_>, ) -> Result<(), Error>

Overwrite caller-provided output with elementwise negation from a read.

fn conj_read(&mut self, input: TensorRead<'_>) -> Result<Tensor, Error>

Errors

fn conj_into( &mut self, input: &Tensor, out: TensorWrite<'_>, ) -> Result<(), Error>

Overwrite caller-provided output with elementwise conjugation.

fn conj_read_into( &mut self, input: TensorRead<'_>, out: TensorWrite<'_>, ) -> Result<(), Error>

Overwrite caller-provided output with elementwise conjugation from a read.

fn div_read( &mut self, lhs: TensorRead<'_>, rhs: TensorRead<'_>, ) -> Result<Tensor, Error>

Errors

fn div_into( &mut self, lhs: &Tensor, rhs: &Tensor, out: TensorWrite<'_>, ) -> Result<(), Error>

Overwrite caller-provided output with elementwise division.

fn div_read_into( &mut self, lhs: TensorRead<'_>, rhs: TensorRead<'_>, out: TensorWrite<'_>, ) -> Result<(), Error>

Overwrite caller-provided output with elementwise division from reads.

fn rem_read( &mut self, lhs: TensorRead<'_>, rhs: TensorRead<'_>, ) -> Result<Tensor, Error>

Elementwise remainder accepting owned tensors or borrowed views.

fn abs_read(&mut self, input: TensorRead<'_>) -> Result<Tensor, Error>

Errors

fn sign_read(&mut self, input: TensorRead<'_>) -> Result<Tensor, Error>

Errors

fn maximum_read( &mut self, lhs: TensorRead<'_>, rhs: TensorRead<'_>, ) -> Result<Tensor, Error>

Errors

fn minimum_read( &mut self, lhs: TensorRead<'_>, rhs: TensorRead<'_>, ) -> Result<Tensor, Error>

Errors

fn compare_read( &mut self, lhs: TensorRead<'_>, rhs: TensorRead<'_>, dir: &CompareDir, ) -> Result<Tensor, Error>

Errors

fn select_read( &mut self, pred: TensorRead<'_>, on_true: TensorRead<'_>, on_false: TensorRead<'_>, ) -> Result<Tensor, Error>

Errors

fn clamp_read( &mut self, input: TensorRead<'_>, lower: TensorRead<'_>, upper: TensorRead<'_>, ) -> Result<Tensor, Error>

Errors

impl TensorFusion for CudaExecSession<'_>

impl TensorIndexing for CudaExecSession<'_>

fn gather( &mut self, operand: &Tensor, start_indices: &Tensor, config: &GatherConfig, ) -> Result<Tensor>

Errors

fn scatter( &mut self, operand: &Tensor, scatter_indices: &Tensor, updates: &Tensor, config: &ScatterConfig, ) -> Result<Tensor>

Errors

fn slice(&mut self, input: &Tensor, config: &SliceConfig) -> Result<Tensor>

Errors

fn dynamic_slice( &mut self, input: &Tensor, starts: &Tensor, slice_sizes: &[usize], ) -> Result<Tensor>

Errors

fn dynamic_update_slice( &mut self, operand: &Tensor, update: &Tensor, starts: &Tensor, ) -> Result<Tensor>

Errors

fn pad(&mut self, input: &Tensor, config: &PadConfig) -> Result<Tensor>

Errors

fn concatenate(&mut self, inputs: &[&Tensor], axis: usize) -> Result<Tensor>

Errors

fn reverse(&mut self, input: &Tensor, axes: &[usize]) -> Result<Tensor>

Errors

impl TensorReduction for CudaExecSession<'_>

fn reduce_sum(&mut self, input: &Tensor, axes: &[usize]) -> Result<Tensor>

Errors

fn reduce_prod(&mut self, input: &Tensor, axes: &[usize]) -> Result<Tensor>

Errors

fn reduce_max(&mut self, input: &Tensor, axes: &[usize]) -> Result<Tensor>

Errors

fn reduce_min(&mut self, input: &Tensor, axes: &[usize]) -> Result<Tensor>

Errors

fn reduce_sum_read( &mut self, input: TensorRead<'_>, axes: &[usize], ) -> Result<Tensor, Error>

Sum elements across axes from an owned tensor or borrowed view.

fn reduce_prod_read( &mut self, input: TensorRead<'_>, axes: &[usize], ) -> Result<Tensor, Error>

Multiply elements across axes from an owned tensor or borrowed view.

fn reduce_max_read( &mut self, input: TensorRead<'_>, axes: &[usize], ) -> Result<Tensor, Error>

Take maximum values across axes from an owned tensor or borrowed view.

fn reduce_min_read( &mut self, input: TensorRead<'_>, axes: &[usize], ) -> Result<Tensor, Error>

Take minimum values across axes from an owned tensor or borrowed view.

impl TensorStructural for CudaExecSession<'_>

fn to_contiguous_read(&mut self, input: TensorRead<'_>) -> Result<Tensor>

Materialize an owned tensor or borrowed view into fresh compact storage.

fn copy_read_into( &mut self, src: TensorRead<'_>, dst: TensorWrite<'_>, ) -> Result<()>

Overwrite caller-provided storage from a readable tensor or view.

fn transpose(&mut self, input: &Tensor, perm: &[usize]) -> Result<Tensor>

Errors

fn reshape(&mut self, input: &Tensor, shape: &[usize]) -> Result<Tensor>

Errors

fn broadcast_in_dim( &mut self, input: &Tensor, shape: &[usize], dims: &[usize], ) -> Result<Tensor>

Errors

fn cast(&mut self, input: &Tensor, to: DType) -> Result<Tensor>

Cast a tensor to another dtype using explicit dtype projection.

fn extract_diagonal( &mut self, input: &Tensor, axis_a: usize, axis_b: usize, ) -> Result<Tensor>

Errors

fn embed_diagonal( &mut self, input: &Tensor, axis_a: usize, axis_b: usize, ) -> Result<Tensor>

Errors

fn tril(&mut self, input: &Tensor, k: i64) -> Result<Tensor>

Errors

fn triu(&mut self, input: &Tensor, k: i64) -> Result<Tensor>

Errors

fn transpose_read( &mut self, input: TensorRead<'_>, perm: &[usize], ) -> Result<Tensor, Error>

Errors

fn reshape_read( &mut self, input: TensorRead<'_>, shape: &[usize], ) -> Result<Tensor, Error>

Errors

fn broadcast_in_dim_read( &mut self, input: TensorRead<'_>, shape: &[usize], dims: &[usize], ) -> Result<Tensor, Error>

Errors

fn convert(&mut self, input: &Tensor, to: DType) -> Result<Tensor, Error>

Convert a tensor to another dtype using checked dtype conversion.