use alloc::vec::Vec;
use core::fmt;
use crate::err::BackendError;
use crate::exec::capability::{
Capabilities, CapabilityQuery, OperationIdentity, SupportLevel, UnsupportedReason,
};
use crate::exec::catalog::{DescriptorError, LogicalTensorMeta, Operation};
use crate::exec::context::ExecutionContext;
use crate::exec::meta::TensorMeta;
use crate::exec::policy::FallbackPolicy;
use crate::exec::request::TensorHandle;
use crate::tensor::backend::{Execute, ExecutionRequest};
#[derive(Debug, Clone, PartialEq)]
pub enum CanonicalError {
Descriptor(DescriptorError),
Policy(PolicyViolation),
Backend(BackendError),
}
impl fmt::Display for CanonicalError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::Descriptor(error) => write!(f, "{error}"),
Self::Policy(error) => write!(f, "{error}"),
Self::Backend(error) => write!(f, "{error}"),
}
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct PolicyViolation {
pub operation: OperationIdentity,
pub support: SupportLevel,
pub fallback: FallbackPolicy,
}
impl fmt::Display for PolicyViolation {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(
f,
"operation {} reports {:?} support, denied by fallback policy {}",
self.operation.display_name(),
self.support,
self.fallback.as_str()
)
}
}
#[cfg(feature = "std")]
impl std::error::Error for CanonicalError {}
impl From<DescriptorError> for CanonicalError {
fn from(error: DescriptorError) -> Self {
Self::Descriptor(error)
}
}
impl From<BackendError> for CanonicalError {
fn from(error: BackendError) -> Self {
Self::Backend(error)
}
}
impl CanonicalError {
#[must_use]
pub const fn unsupported(backend: &'static str, reason: UnsupportedReason) -> Self {
Self::Backend(BackendError::unsupported(backend, reason))
}
}
#[must_use]
pub fn logical_meta(metadata: &TensorMeta) -> LogicalTensorMeta {
LogicalTensorMeta {
shape: Some(metadata.shape.clone()),
dtype: Some(metadata.dtype),
device: Some(metadata.device),
}
}
fn admit<B: Capabilities>(
backend: &B,
operation: &OperationIdentity,
metadata: &TensorMeta,
context_training: bool,
math_mode: crate::exec::policy::MathMode,
) -> Result<SupportLevel, UnsupportedReason> {
let query = CapabilityQuery {
operation: operation.clone(),
dtype: metadata.dtype,
layout: metadata.layout,
rank: metadata.shape.dims().len(),
training: context_training,
math_mode,
};
match backend.support(&query) {
SupportLevel::Unsupported(reason) => Err(reason),
level => Ok(level),
}
}
fn admit_support(
backend: &'static str,
operation: &OperationIdentity,
support: SupportLevel,
fallback: FallbackPolicy,
) -> Result<(), CanonicalError> {
match support {
SupportLevel::Native => Ok(()),
SupportLevel::Composed if fallback.allows_composition() => Ok(()),
SupportLevel::Fallback if fallback.allows_transfer() => Ok(()),
SupportLevel::Unsupported(reason) => Err(CanonicalError::unsupported(backend, reason)),
support @ (SupportLevel::Composed | SupportLevel::Fallback) => {
Err(CanonicalError::Policy(PolicyViolation {
operation: operation.clone(),
support,
fallback,
}))
}
}
}
fn admit_operation<O, B>(
backend: &B,
operation: &OperationIdentity,
metadata: &TensorMeta,
context_training: bool,
math_mode: crate::exec::policy::MathMode,
fallback: FallbackPolicy,
) -> Result<(), CanonicalError>
where
O: Operation,
B: Capabilities + Execute<O>,
{
let query = CapabilityQuery {
operation: operation.clone(),
dtype: metadata.dtype,
layout: metadata.layout,
rank: metadata.shape.dims().len(),
training: context_training,
math_mode,
};
let support = match operation {
OperationIdentity::Builtin(_) => Capabilities::support(backend, &query),
OperationIdentity::Custom(_) => Execute::<O>::supports_custom(backend, &query),
};
admit_support(B::BACKEND_NAME, operation, support, fallback)
}
fn admit_metadata_free_operation<O, B>(
backend: &B,
operation: &OperationIdentity,
training: bool,
math_mode: crate::exec::policy::MathMode,
fallback: FallbackPolicy,
) -> Result<(), CanonicalError>
where
O: Operation,
B: Execute<O>,
{
let OperationIdentity::Custom(_) = operation else {
return Ok(());
};
admit_support(
B::BACKEND_NAME,
operation,
Execute::<O>::supports_custom_operation(backend, operation, training, math_mode),
fallback,
)
}
fn admit_invocation<O, B>(
context: &ExecutionContext<B>,
invocation: &crate::exec::catalog::ValidatedInvocation<O>,
inputs: &[TensorHandle<'_>],
) -> Result<(), CanonicalError>
where
O: Operation,
B: Capabilities + Execute<O>,
{
let training = context.training();
let fallback = context.fallback();
let identity = invocation.descriptor().identity();
for handle in inputs {
admit_operation::<O, B>(
context.backend(),
identity,
handle.metadata(),
training,
context.math_mode(),
fallback,
)?;
}
if !inputs.is_empty() {
return Ok(());
}
let mut queried = false;
for output in invocation.descriptor().outputs() {
let (Some(dtype), Some(shape)) = (output.dtype, output.shape.as_deref()) else {
continue;
};
queried = true;
let query = CapabilityQuery {
operation: identity.clone(),
dtype,
layout: crate::exec::meta::LayoutClass::Contiguous,
rank: shape.len(),
training,
math_mode: context.math_mode(),
};
let support = match identity {
OperationIdentity::Builtin(_) => Capabilities::support(context.backend(), &query),
OperationIdentity::Custom(_) => {
Execute::<O>::supports_custom(context.backend(), &query)
}
};
admit_support(B::BACKEND_NAME, identity, support, fallback)?;
}
if !queried {
admit_metadata_free_operation::<O, B>(
context.backend(),
identity,
training,
context.math_mode(),
fallback,
)?;
}
Ok(())
}
pub fn execute<O, B>(
context: &ExecutionContext<B>,
attributes: O::Attributes,
inputs: &[TensorHandle<'_>],
) -> Result<<B as Execute<O>>::Output, CanonicalError>
where
O: Operation,
B: Execute<O> + Capabilities,
{
execute_with_payload(context, attributes, inputs, None)
}
pub fn execute_with_payload<O, B>(
context: &ExecutionContext<B>,
attributes: O::Attributes,
inputs: &[TensorHandle<'_>],
payload: Option<&[u8]>,
) -> Result<<B as Execute<O>>::Output, CanonicalError>
where
O: Operation,
B: Execute<O> + Capabilities,
{
let logical: Vec<LogicalTensorMeta> = inputs
.iter()
.map(|handle| logical_meta(handle.metadata()))
.collect();
let invocation = O::infer_invocation(attributes, logical)?;
validate_execution_payload::<O>(&invocation, payload)?;
admit_invocation::<O, B>(context, &invocation, inputs)?;
context
.backend()
.execute(ExecutionRequest {
operation: invocation.validated(),
inputs,
context,
payload,
})
.map_err(CanonicalError::Backend)
}
pub fn execute_shaped<O, B, S>(
context: &ExecutionContext<B>,
attributes: O::Attributes,
inputs: &[TensorHandle<'_>],
expected: &crate::shapes::ShapeValue<S>,
) -> Result<<B as Execute<O>>::Output, CanonicalError>
where
O: Operation,
B: Execute<O> + Capabilities,
S: crate::shapes::Shape,
{
execute_shaped_with_payload(context, attributes, inputs, expected, None)
}
pub fn execute_shaped_with_payload<O, B, S>(
context: &ExecutionContext<B>,
attributes: O::Attributes,
inputs: &[TensorHandle<'_>],
expected: &crate::shapes::ShapeValue<S>,
payload: Option<&[u8]>,
) -> Result<<B as Execute<O>>::Output, CanonicalError>
where
O: Operation,
B: Execute<O> + Capabilities,
S: crate::shapes::Shape,
{
let logical: Vec<LogicalTensorMeta> = inputs
.iter()
.map(|handle| logical_meta(handle.metadata()))
.collect();
let invocation = O::infer_invocation_typed(attributes, logical, expected)?;
validate_execution_payload::<O>(&invocation, payload)?;
admit_invocation::<O, B>(context, &invocation, inputs)?;
context
.backend()
.execute(ExecutionRequest {
operation: invocation.validated(),
inputs,
context,
payload,
})
.map_err(CanonicalError::Backend)
}
fn validate_execution_payload<O>(
invocation: &crate::exec::catalog::ValidatedInvocation<O>,
payload: Option<&[u8]>,
) -> Result<(), CanonicalError>
where
O: Operation,
{
let attributes = invocation.descriptor().attributes();
let data =
(attributes as &dyn core::any::Any).downcast_ref::<crate::exec::catalog::DataAttributes>();
let operation = match invocation.descriptor().identity() {
OperationIdentity::Builtin(operation) => operation,
OperationIdentity::Custom(_) => return Ok(()),
};
match data {
Some(data) => match payload {
Some(bytes) if bytes.len() == data.payload.byte_len() => Ok(()),
Some(bytes) => Err(CanonicalError::Descriptor(
crate::exec::catalog::DescriptorError::PayloadByteLength {
operation: *operation,
expected: data.payload.byte_len(),
actual: bytes.len(),
},
)),
None => Err(CanonicalError::Descriptor(
crate::exec::catalog::DescriptorError::PayloadMissing {
operation: *operation,
},
)),
},
None if payload.is_some() => Err(CanonicalError::Descriptor(
crate::exec::catalog::DescriptorError::UnexpectedPayload {
operation: *operation,
},
)),
None => Ok(()),
}
}
pub fn support_for<O, B>(
context: &ExecutionContext<B>,
metadata: &TensorMeta,
) -> Result<SupportLevel, UnsupportedReason>
where
O: crate::exec::catalog::CanonicalOperation,
B: Capabilities + crate::tensor::backend::StorageBackend,
{
admit(
context.backend(),
&OperationIdentity::Builtin(O::ID),
metadata,
context.training(),
context.math_mode(),
)
}