use crate::shapes::error::OperationKind;
use crate::tensor::device::DeviceId;
use crate::tensor::dtype::DTypeDescriptor;
#[cfg(test)]
use crate::tensor::dtype::DTypeId;
use alloc::string::String;
use alloc::string::ToString;
use alloc::vec::Vec;
use core::fmt::Debug;
pub const MAX_ERROR_MESSAGE_BYTES: usize = 512;
#[derive(Clone, PartialEq, Eq)]
pub struct ErrorMessage(String);
impl ErrorMessage {
#[must_use]
pub fn new(message: impl AsRef<str>) -> Self {
let message = message.as_ref();
let mut end = message.len().min(MAX_ERROR_MESSAGE_BYTES);
while !message.is_char_boundary(end) {
end -= 1;
}
Self(message[..end].to_string())
}
#[must_use]
pub fn as_str(&self) -> &str {
&self.0
}
}
impl core::fmt::Debug for ErrorMessage {
fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
self.0.fmt(f)
}
}
impl core::fmt::Display for ErrorMessage {
fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
f.write_str(&self.0)
}
}
impl From<String> for ErrorMessage {
fn from(message: String) -> Self {
Self::new(message)
}
}
impl From<&str> for ErrorMessage {
fn from(message: &str) -> Self {
Self::new(message)
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum FloatToIntPolicy {
Exact,
Truncate,
Saturate,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ConversionFailure {
NonFinite,
Fractional,
OutOfRange,
}
impl core::fmt::Display for ConversionFailure {
fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
f.write_str(match self {
Self::NonFinite => "non-finite value",
Self::Fractional => "fractional value",
Self::OutOfRange => "out-of-range value",
})
}
}
#[non_exhaustive]
#[derive(thiserror::Error, Debug, Clone, PartialEq, Eq)]
pub enum BackendError {
#[error("backend '{backend}' refused the request: {reason}")]
Unsupported {
backend: &'static str,
reason: crate::exec::capability::UnsupportedReason,
},
#[error("invalid input for {operation}: {reason}")]
InvalidInput {
operation: crate::shapes::error::OperationKind,
reason: &'static str,
},
#[error("backend execution failed for {operation}: {message}")]
Execution {
operation: crate::shapes::error::OperationKind,
message: ErrorMessage,
},
#[error("device {device:?} was lost during execution")]
DeviceLost {
device: crate::tensor::device::DeviceId,
},
}
impl BackendError {
#[must_use]
pub const fn unsupported(
backend: &'static str,
reason: crate::exec::capability::UnsupportedReason,
) -> Self {
Self::Unsupported { backend, reason }
}
}
#[non_exhaustive]
#[derive(thiserror::Error, Debug, Clone, PartialEq, Eq)]
pub enum BackwardError {
#[error("gradient for tensor {tensor} is not finite (produced by {operation})")]
NonFinite {
tensor: u64,
operation: NonFiniteSite,
},
#[error("backward recipe for {operation} could not produce a gradient: {reason}")]
Recipe {
operation: crate::shapes::error::OperationKind,
reason: &'static str,
},
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum NonFiniteSite {
Contribution,
Accumulation,
}
impl core::fmt::Display for NonFiniteSite {
fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
f.write_str(match self {
Self::Contribution => "a backward recipe",
Self::Accumulation => "accumulating two contributions",
})
}
}
pub type Result<T> = core::result::Result<T, Error>;
#[non_exhaustive]
#[derive(thiserror::Error)]
pub enum Error {
#[error(transparent)]
Backend(#[from] BackendError),
#[error("{0}")]
Descriptor(crate::exec::catalog::DescriptorError),
#[error("{0}")]
Policy(crate::exec::PolicyViolation),
#[error(transparent)]
Backward(#[from] BackwardError),
#[error("Backend '{backend}' is unavailable in this build")]
BackendUnavailable {
backend: &'static str,
},
#[error("Dtype {dtype:?} is unsupported by backend '{backend}' for '{op}'")]
UnsupportedDType {
dtype: DTypeDescriptor,
backend: &'static str,
op: &'static str,
},
#[error(
"Precision choice {requested:?} for {role:?} role is unsupported for operation '{operation:?}', storage {storage:?} on backend '{backend}'"
)]
UnsupportedPrecision {
operation: OperationKind,
storage: DTypeDescriptor,
requested: DTypeDescriptor,
role: crate::exec::PrecisionRole,
backend: &'static str,
},
#[error("Tensor dtype metadata {expected:?} does not match storage {got:?}")]
DTypeStorageMismatch {
expected: DTypeDescriptor,
got: DTypeDescriptor,
},
#[error("{operation}: cannot convert {from:?} to {to:?}: {reason}")]
InvalidConversion {
operation: &'static str,
from: DTypeDescriptor,
to: DTypeDescriptor,
reason: ConversionFailure,
},
#[error("{operation}: dtype mismatch: expected {expected:?}, got {actual:?}")]
DTypeMismatch {
operation: &'static str,
expected: DTypeDescriptor,
actual: DTypeDescriptor,
},
#[error("Tensor device metadata {expected:?} does not match storage {got:?}")]
DeviceStorageMismatch {
expected: DeviceId,
got: DeviceId,
},
#[error("Device mismatch: left {left:?}, right {right:?}")]
DeviceMismatch {
left: DeviceId,
right: DeviceId,
},
#[error("{operation}: device or placement mismatch: expected {expected:?}, got {actual:?}")]
PlacementMismatch {
operation: &'static str,
expected: DeviceId,
actual: DeviceId,
},
#[error("Invalid byte length: expected {expected}, got {got}")]
InvalidByteLength {
expected: usize,
got: usize,
},
#[error("Invalid {backend} device ordinal {ordinal}")]
InvalidDeviceOrdinal {
backend: &'static str,
ordinal: usize,
},
#[error("{operation}: arithmetic overflow evaluating '{expression}'")]
ArithmeticOverflow {
operation: &'static str,
expression: &'static str,
},
#[error("{operation}: allocation of {requested} bytes exceeds limit {limit}")]
AllocationOverflow {
operation: &'static str,
requested: u64,
limit: u64,
},
#[error("{0}")]
Shape(#[from] crate::shapes::error::ShapeError),
#[error("Shape mismatch during '{op}': expected {expected:?}, got {got:?}. {msg}")]
ShapeMismatch {
op: &'static str,
expected: Vec<usize>,
got: Vec<usize>,
msg: String,
},
#[error("Out of Memory error on device: {device}")]
OutOfMemory {
device: String,
},
#[error("Operation '{op}' is not supported by backend '{backend}'")]
UnsupportedBackendOperation {
op: &'static str,
backend: &'static str,
},
#[error("Invalid device provided: expected {expected}, got {got}")]
DeviceInitializationError {
expected: String,
got: String,
},
#[error("{operation}: invalid module or state dictionary: {reason}")]
InvalidModuleState {
operation: &'static str,
reason: ErrorMessage,
},
#[error("{operation}: malformed {artifact}: {reason}")]
MalformedArtifact {
operation: &'static str,
artifact: &'static str,
reason: ErrorMessage,
},
#[error("{operation}: resource '{resource}' value {actual} exceeds limit {limit}")]
ResourceLimit {
operation: &'static str,
resource: &'static str,
actual: u64,
limit: u64,
},
#[error("{operation}: I/O failure: {message}")]
Io {
operation: &'static str,
message: ErrorMessage,
},
#[error("{operation}: internal invariant violation: {reason}")]
InternalInvariant {
operation: &'static str,
reason: &'static str,
},
#[error("Internal Backend Failure: {0}")]
BackendFailure(#[from] anyhow::Error),
#[error("Generic Message: {0}")]
Msg(String),
}
#[cfg(feature = "std")]
impl From<std::io::Error> for Error {
fn from(err: std::io::Error) -> Self {
Error::Io {
operation: "io",
message: ErrorMessage::new(err.to_string()),
}
}
}
impl From<crate::exec::CanonicalError> for Error {
fn from(error: crate::exec::CanonicalError) -> Self {
match error {
crate::exec::CanonicalError::Descriptor(error) => Self::Descriptor(error),
crate::exec::CanonicalError::Policy(error) => Self::Policy(error),
crate::exec::CanonicalError::Backend(error) => Self::Backend(error),
}
}
}
impl From<crate::exec::MetaError> for Error {
fn from(err: crate::exec::MetaError) -> Self {
match err {
crate::exec::MetaError::Shape(s) => Error::Shape(s),
other => Error::InternalInvariant {
operation: "tensor_metadata",
reason: match other {
crate::exec::MetaError::InvalidAlignment { .. } => {
"metadata alignment is invalid"
}
crate::exec::MetaError::OutOfBounds { .. } => {
"metadata addresses storage outside its allocation"
}
crate::exec::MetaError::Shape(_) => {
"metadata shape error bypassed its structured conversion"
}
},
},
}
}
}
pub fn convert_f64_to_i64(
operation: &'static str,
from: DTypeDescriptor,
value: f64,
policy: FloatToIntPolicy,
) -> Result<i64> {
if value.is_nan() {
return Err(Error::InvalidConversion {
operation,
from,
to: <i64 as crate::tensor::dtype::ConstDType>::DESCRIPTOR,
reason: ConversionFailure::NonFinite,
});
}
if value.is_infinite() {
return match policy {
FloatToIntPolicy::Saturate => Ok(if value.is_sign_negative() {
i64::MIN
} else {
i64::MAX
}),
FloatToIntPolicy::Exact | FloatToIntPolicy::Truncate => Err(Error::InvalidConversion {
operation,
from,
to: <i64 as crate::tensor::dtype::ConstDType>::DESCRIPTOR,
reason: ConversionFailure::NonFinite,
}),
};
}
let candidate = match policy {
FloatToIntPolicy::Exact if value.fract() != 0.0 => {
return Err(Error::InvalidConversion {
operation,
from,
to: <i64 as crate::tensor::dtype::ConstDType>::DESCRIPTOR,
reason: ConversionFailure::Fractional,
});
}
FloatToIntPolicy::Exact | FloatToIntPolicy::Truncate => value.trunc(),
FloatToIntPolicy::Saturate => value,
};
const I64_MIN_F64: f64 = -9_223_372_036_854_775_808.0;
const I64_MAX_EXCLUSIVE_F64: f64 = 9_223_372_036_854_775_808.0;
if !(I64_MIN_F64..I64_MAX_EXCLUSIVE_F64).contains(&candidate) {
return match policy {
FloatToIntPolicy::Saturate => Ok(if candidate.is_sign_negative() {
i64::MIN
} else {
i64::MAX
}),
FloatToIntPolicy::Exact | FloatToIntPolicy::Truncate => Err(Error::InvalidConversion {
operation,
from,
to: <i64 as crate::tensor::dtype::ConstDType>::DESCRIPTOR,
reason: ConversionFailure::OutOfRange,
}),
};
}
Ok(candidate as i64)
}
impl Debug for Error {
fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
write!(f, "{self}")
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn error_message_is_bounded_at_a_utf8_boundary() {
let ascii = ErrorMessage::new("x".repeat(MAX_ERROR_MESSAGE_BYTES + 32));
assert_eq!(ascii.as_str().len(), MAX_ERROR_MESSAGE_BYTES);
let unicode = ErrorMessage::new(format!("{}é", "x".repeat(MAX_ERROR_MESSAGE_BYTES - 1)));
assert_eq!(unicode.as_str().len(), MAX_ERROR_MESSAGE_BYTES - 1);
assert!(unicode.as_str().is_char_boundary(unicode.as_str().len()));
}
#[test]
fn exact_float_to_integer_conversion_rejects_lossy_values() {
assert_eq!(
convert_f64_to_i64(
"index_readback",
DTypeId::F64.descriptor(),
42.0,
FloatToIntPolicy::Exact,
)
.unwrap(),
42
);
for (value, expected) in [
(42.5, ConversionFailure::Fractional),
(f64::NAN, ConversionFailure::NonFinite),
(f64::INFINITY, ConversionFailure::NonFinite),
(f64::NEG_INFINITY, ConversionFailure::NonFinite),
(9_223_372_036_854_775_808.0, ConversionFailure::OutOfRange),
(-9_223_372_036_854_777_856.0, ConversionFailure::OutOfRange),
] {
let err = convert_f64_to_i64(
"index_readback",
DTypeId::F64.descriptor(),
value,
FloatToIntPolicy::Exact,
)
.unwrap_err();
if let Error::InvalidConversion {
operation,
from,
to,
reason,
} = err
{
assert_eq!(operation, "index_readback");
assert_eq!(from, DTypeId::F64.descriptor());
assert_eq!(to, DTypeId::I64.descriptor());
assert_eq!(reason, expected);
} else {
panic!("expected Error::InvalidConversion");
}
}
}
#[test]
fn lossy_float_to_integer_conversion_requires_an_explicit_policy() {
assert_eq!(
convert_f64_to_i64(
"explicit_truncate",
DTypeId::F64.descriptor(),
-42.75,
FloatToIntPolicy::Truncate,
)
.unwrap(),
-42
);
assert_eq!(
convert_f64_to_i64(
"explicit_saturate",
DTypeId::F64.descriptor(),
f64::INFINITY,
FloatToIntPolicy::Saturate,
)
.unwrap(),
i64::MAX
);
assert_eq!(
convert_f64_to_i64(
"explicit_saturate",
DTypeId::F64.descriptor(),
f64::NEG_INFINITY,
FloatToIntPolicy::Saturate,
)
.unwrap(),
i64::MIN
);
assert!(matches!(
convert_f64_to_i64(
"explicit_saturate",
DTypeId::F64.descriptor(),
f64::NAN,
FloatToIntPolicy::Saturate,
),
Err(Error::InvalidConversion {
reason: ConversionFailure::NonFinite,
..
})
));
}
#[test]
fn test_error_formatting() {
let err = Error::OutOfMemory {
device: "CUDA:0".to_string(),
};
let formatted = alloc::format!("{}", err);
assert_eq!(formatted, "Out of Memory error on device: CUDA:0");
let err_unsupported = Error::UnsupportedBackendOperation {
op: "matmul",
backend: "Ndarray",
};
let formatted = alloc::format!("{}", err_unsupported);
assert_eq!(
formatted,
"Operation 'matmul' is not supported by backend 'Ndarray'"
);
}
}