Trait BackendSession 

pub trait BackendSession:
    TensorBackendOps
    + SessionCachedDot
    + TensorDeviceTransfer {
    // Provided methods
    fn vdot_read(
        &mut self,
        _lhs: TensorRead<'_>,
        _rhs: TensorRead<'_>,
    ) -> Result<Tensor, Error> { ... }
    fn norm_squared_read(
        &mut self,
        _input: TensorRead<'_>,
    ) -> Result<Tensor, Error> { ... }
    fn axpby_read_into_accum(
        &mut self,
        _alpha: ContractionScalar,
        _x: TensorRead<'_>,
        _beta: ContractionScalar,
        _y: TensorWrite<'_>,
    ) -> Result<(), Error> { ... }
    fn native_session(&mut self) -> Option<NativeSessionRef<'_>> { ... }
}

Execution session surface for dense tensor backends.

All operations run within a backend-owned execution scope such as a CPU thread policy or a GPU stream. Individual ops must not try to re-enter that scope.

Examples

use tenferro_tensor::{BackendSessionHost, Tensor, TensorRead, TypedTensor};

fn add_in_session<B: BackendSessionHost>(
    backend: &mut B,
    a: &Tensor,
    b: &Tensor,
) -> tenferro_tensor::Result<Tensor>
where
    B: tenferro_tensor::TensorBackend,
{
    // Admission failure converts into `tenferro_tensor::Error::SessionEntry`;
    // the operation's own result is returned unchanged.
    backend.with_backend_session(|exec| {
        exec.add_read(TensorRead::from_tensor(a), TensorRead::from_tensor(b))
    })?
}

The operation one-shot spelling is gone; a session only answers to the read form:

use tenferro_tensor::{BackendSessionHost, Tensor, TensorBackend};

fn add_in_session<B: BackendSessionHost + TensorBackend>(
    backend: &mut B,
    a: &Tensor,
    b: &Tensor,
) {
    backend.with_backend_session(|exec| {
        let _ = exec.add(a, b);
    });
}

Provided Methods

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

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

The result is a rank-0 tensor with the input dtype and has the value sum(conj(lhs) * rhs). Borrowed views remain borrowed through the backend’s existing same-placement planning boundary.

Examples

use tenferro_tensor::{BackendSession, TensorRead};

fn vdot(session: &mut dyn BackendSession, x: TensorRead<'_>, y: TensorRead<'_>)
    -> tenferro_tensor::Result<tenferro_tensor::Tensor>
{
    session.vdot_read(x, y)
}

Errors

Returns Error::Unsupported when the backend does not override this capability or the dtype is unsupported; Error::Validation with DTypeMismatch, ShapeMismatch, or InvalidArgument when dtype, shape, or placement differs; Error::RuntimeState for inaccessible backend storage; or Error::BackendSource when provider execution fails.

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

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

The result is rank 0 and is F32 for F32/C32 input or F64 for F64/C64 input. No transfer or full-size algebra temporary is implied by this session contract.

Examples

use tenferro_tensor::{BackendSession, TensorRead};

fn norm_squared(session: &mut dyn BackendSession, x: TensorRead<'_>)
    -> tenferro_tensor::Result<tenferro_tensor::Tensor>
{
    session.norm_squared_read(x)
}

Errors

Returns Error::Unsupported when the backend does not override this capability or the dtype is unsupported, Error::RuntimeState when backend storage is not host-accessible, or Error::BackendSource when reduction execution fails.

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.

Scalars must have the exact tensor dtype; real coefficients for complex vectors are represented as complex values with zero imaginary part. The destination must be compact and injective, and any x/y storage overlap is rejected before mutation.

Examples

use tenferro_tensor::{BackendSession, ContractionScalar, TensorRead, TensorWrite};

fn axpby(session: &mut dyn BackendSession, x: TensorRead<'_>, y: TensorWrite<'_>)
    -> tenferro_tensor::Result<()>
{
    session.axpby_read_into_accum(
        ContractionScalar::F64(1.0), x, ContractionScalar::F64(0.0), y,
    )
}

Errors

Returns Error::Unsupported when the backend does not override this capability or the dtype is unsupported; Error::Validation with DTypeMismatch, ShapeMismatch, or InvalidArgument for scalar/dtype, shape, placement, compactness, injectivity, or overlap failures; or Error::RuntimeState for inaccessible backend storage. Invalid requests leave the destination unchanged.

fn native_session(&mut self) -> Option<NativeSessionRef<'_>>

Return this session’s backend-leaf native capability, if it has one.

Standard CPU, CUDA and WebGPU sessions return a token their own safe visitors (with_cpu_exec_session, with_cuda_exec_session, with_webgpu_exec_session) recover. The default is None: a custom session has no native services unless it forwards the token of a standard session it owns. A wrapper that overrides operation dispatch (for example a custom GEMM) should keep the default, because an operation family that finds a native token may call the delegate’s native services directly and so bypass the wrapper’s override.

Examples

use tenferro_tensor::BackendSession;

fn native_services_available(session: &mut dyn BackendSession) -> bool {
    session.native_session().is_some()
}

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors