Skip to main content

Error

Struct Error 

Source
pub struct Error { /* private fields */ }
Expand description

An error that crosses the FFI boundary, with a kind, a message and a backtrace.

An Error raised in another language arrives in Rust as an Err, and one returned from a Rust Function is raised in the caller’s language. Create one with bail! or ensure!, which also record the source location.

§Examples

use tvm_ffi::{bail, Result, VALUE_ERROR};

fn parse_digit(c: char) -> Result<u32> {
    match c.to_digit(10) {
        Some(digit) => Ok(digit),
        None => bail!(VALUE_ERROR, "not a digit: {:?}", c),
    }
}

let error = parse_digit('x').unwrap_err();
assert_eq!(error.kind(), VALUE_ERROR);
assert_eq!(error.message(), "not a digit: 'x'");

An Error is Send + Sync, so a Result can cross threads.

Implementations§

Source§

impl Error

Source

pub fn from_panic(payload: Box<dyn Any + Send>) -> Self

The InternalError for a panic caught at an FFI boundary, where unwinding into the caller would abort the process. The message is the panic’s, when it is a string.

use tvm_ffi::{Error, INTERNAL_ERROR};
let payload = std::panic::catch_unwind(|| panic!("bad state")).unwrap_err();
let error = Error::from_panic(payload);
assert_eq!(error.kind(), INTERNAL_ERROR);
assert_eq!(error.message(), "panicked: bad state");
Source

pub fn downcast_failed<B: AnyCompatible>(source: impl ObjectRefCore) -> Self

The TypeError for a reference that downcast handed back because it is not a B, naming both types.

use tvm_ffi::{object::ObjectRef, Array, Error, ObjectRefCore, TYPE_ERROR};
let object: ObjectRef = Array::from_vec(vec![1_i64]).into();
let error = object.downcast::<Array<f64>>().map_err(Error::downcast_failed::<Array<f64>>);
assert_eq!(error.unwrap_err().kind(), TYPE_ERROR);
Source

pub fn new(kind: ErrorKind<'_>, message: &str) -> Self

Create an error with an empty backtrace.

Prefer format_err! or bail!, which also record the source location. Add the other parts with with_backtrace, with_cause and with_extra_context.

§Arguments
  • kind - The kind of the error, such as VALUE_ERROR.
  • message - The message of the error.
§Returns

The error.

Source

pub fn with_cause(self, cause: &Error) -> Self

Set cause as the error that caused this one, the cause_chain. The error is updated in place when it is not shared, and copied otherwise.

use tvm_ffi::{Error, RUNTIME_ERROR, VALUE_ERROR};
let cause = Error::new(VALUE_ERROR, "bad input");
let error = Error::new(RUNTIME_ERROR, "load failed").with_cause(&cause);
assert_eq!(error.cause_chain().unwrap().message(), "bad input");
Source

pub fn with_extra_context<T: ObjectRefCore + Send + Sync>( self, context: &T, ) -> Self

Set context as the extra_context, an object of application-specific context; Send + Sync, since the error is. The error is updated in place when it is not shared, and copied otherwise.

Source

pub fn from_raised() -> Self

Create a new error by moving from the error that the last failed FFI call raised on this thread, as set by Error::set_raised. An associated function rather than a constructor from a value: it takes the thread’s state.

§Returns

The raised error.

§Panics

Panics if no error was raised.

Source

pub fn set_raised(error: &Self)

Set error as the raised error of the calling thread, for the caller of an extern "C" function, which then returns -1, to take with Error::from_raised. An associated function rather than a method: it changes the thread’s state, not error.

§Arguments
  • error - The error to set as raised.
Source

pub fn kind(&self) -> ErrorKind<'_>

Get the kind of the error.

§Returns

The kind of the error, such as VALUE_ERROR.

Source

pub fn message(&self) -> &str

Get the message of the error.

§Returns

The message of the error.

Source

pub fn backtrace(&self) -> &str

Get the backtrace of the error.

It may be rewritten when the error is re-raised through another language: copy it to keep it across FFI calls.

§Returns

The backtrace, most recent call first.

Source

pub fn cause_chain(&self) -> Option<&Error>

The error that caused this one, the next link of the cause chain; the same error that std::error::Error::source returns.

Source

pub fn extra_context(&self) -> Option<&ObjectRef>

The application-specific context object, if present.

The context is shared with every thread the error reaches, so it must be safe to share; a context set by another language is the setter’s responsibility.

Source

pub fn traceback_most_recent_call_last(&self) -> String

Get the traceback of the error in the order of most recent call last, as Python prints it.

§Returns

The traceback of the error.

Source

pub fn with_backtrace(self, backtrace: &str) -> Self

Replace the backtrace, most recent call first. The error is updated in place when it is not shared, and copied otherwise.

Source

pub fn with_appended_backtrace(self, backtrace: &str) -> Self

Append the backtrace to the error.

attach_context! appends the current source location this way. The error is updated in place when it is not shared, and copied otherwise.

§Arguments
  • backtrace - The backtrace to append.
§Returns

The error with the appended backtrace.

Trait Implementations§

Source§

impl AsRef<Error> for Error

Source§

fn as_ref(&self) -> &Self

Converts this type into a shared reference of the (usually inferred) input type.
Source§

impl AsRef<ObjectRef> for Error

Source§

fn as_ref(&self) -> &ObjectRef

Converts this type into a shared reference of the (usually inferred) input type.
Source§

impl Clone for Error

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Debug for Error

Formats the traceback, most recent call last, then the kind and the message, as Python prints an exception; unwrap and expect print it.

Source§

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

Formats the value using the given formatter. Read more
Source§

impl Display for Error

Formats the kind and the message, such as ValueError: bad x, as C++ what(); Debug adds the traceback.

Source§

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

Formats the value using the given formatter. Read more
Source§

impl DowncastRefFromAny for Error

Source§

unsafe fn downcast_ref_from_any(cell: &TVMFFIAny) -> Option<&Self>

Borrow cell as Self when it holds one. Read more
Source§

impl Error for Error

Source§

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any. Read more
1.0.0 · Source§

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

1.0.0 · Source§

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

Source§

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)
Provides type-based access to context intended for error reports. Read more
Source§

impl From<&Error> for Error

Source§

fn from(value: &Error) -> Self

Converts to this type from the input type.
Source§

impl From<&Error> for ObjectRef

Source§

fn from(value: &Error) -> Self

Converts to this type from the input type.
Source§

impl From<Error> for ObjectRef

Source§

fn from(value: Error) -> Self

Converts to this type from the input type.
Source§

impl IntoArg<Error> for Error

Source§

type Output = Error

T when owned, &T when borrowed.
Source§

fn into_arg(self) -> Error

Convert into a T or a &T.
Source§

fn into_owned(self) -> Error

Convert into an owned T, cloning only a borrowed value.
Source§

impl<'a> IntoArg<Error> for &'a Error

Source§

type Output = &'a Error

T when owned, &T when borrowed.
Source§

fn into_arg(self) -> &'a Error

Convert into a T or a &T.
Source§

fn into_owned(self) -> Error

Convert into an owned T, cloning only a borrowed value.
Source§

impl IntoArg<ObjectRef> for Error

Source§

type Output = ObjectRef

T when owned, &T when borrowed.
Source§

fn into_arg(self) -> ObjectRef

Convert into a T or a &T.
Source§

fn into_owned(self) -> ObjectRef

Convert into an owned T, cloning only a borrowed value.
Source§

impl<'a> IntoArg<ObjectRef> for &'a Error

Source§

type Output = &'a ObjectRef

T when owned, &T when borrowed.
Source§

fn into_arg(self) -> &'a ObjectRef

Convert into a T or a &T.
Source§

fn into_owned(self) -> ObjectRef

Convert into an owned T, cloning only a borrowed value.
Source§

impl ObjectRefAnyCompatible for Error

Source§

fn extra_check(obj: &Self::ContainerType) -> bool

Whether obj, an instance of ContainerType, is a value of Self. Every strict and converting cast checks it, after the object type.
Source§

fn convert_fallback(value: AnyView<'_>) -> Option<Self>

Convert a value that is not a Self object, such as an integer that stands for a constant; None rejects it. Only converting casts (TryFrom<Any>, typed function arguments) call it; downcast_ref, downcast and match_any! never do.
Source§

fn custom_type_str() -> String

The type name in conversion errors and type schemas; by default the object’s type key. See AnyCompatible::type_str.
Source§

fn custom_mismatch_type_info(value: AnyView<'_>) -> String

The name of the mismatched value in conversion errors; by default its runtime type key. See AnyCompatible::get_mismatch_type_info.
Source§

impl ObjectRefCore for Error

Source§

type ContainerType = ErrorObj

The object type the reference points to.
Source§

fn data(this: &Self) -> &ObjectArc<Self::ContainerType>

Borrow the object’s handle.
Source§

fn into_data(this: Self) -> ObjectArc<Self::ContainerType>

Take the object’s handle.
Source§

unsafe fn from_data(data: ObjectArc<Self::ContainerType>) -> Self

Make a reference from the object’s handle. Read more
Source§

fn same_as<Other: ObjectRefCore>(&self, other: &Other) -> bool

Whether two references point to the same object.
Source§

fn type_key(&self) -> &'static str

The registered type key of the object’s runtime type, such as "ffi.Array", as C++ ObjectRef::GetTypeKey.
Source§

fn is<T: AnyCompatible>(&self) -> bool

Whether the reference is a T as is, such as a subtype or a container whose elements are checked too, by the strict check of downcast, without a reference count change. See also crate::Any::is.
Source§

fn downcast_ref<T: DowncastRefFromObject>(&self) -> Option<&T>

Borrow the underlying object as T when it is one. Read more
Source§

fn downcast<B>(self) -> Result<B, Self>
where B: ObjectRefCore,

Take self as B, a subtype or a container such as Array<i64> whose elements are checked too, when its object is one, without copying it. On a mismatch the reference is returned unchanged. Read more
Source§

impl PackedCallArg for Error

Source§

type Holder = Error

What keeps the argument alive during the call.
Source§

fn into_packed_arg(self) -> Error

Source§

fn as_packed_arg(holder: &Self::Holder) -> AnyView<'_>

Source§

impl<'a> PackedCallArg for &'a Error

Source§

type Holder = &'a Error

What keeps the argument alive during the call.
Source§

fn into_packed_arg(self) -> &'a Error

Source§

fn as_packed_arg(holder: &Self::Holder) -> AnyView<'_>

Source§

impl Send for Error

Source§

impl Sync for Error

Source§

impl<'a> TryFrom<&'a Any> for Error

Source§

type Error = Error

The type returned in the event of a conversion error.
Source§

fn try_from(value: &'a Any) -> Result<Self, Self::Error>

Performs the conversion.
Source§

impl TryFrom<&ObjectRef> for Error

Source§

type Error = Error

The type returned in the event of a conversion error.
Source§

fn try_from(value: &ObjectRef) -> Result<Self, Self::Error>

Performs the conversion.
Source§

impl TryFrom<Any> for Error

Source§

type Error = Error

The type returned in the event of a conversion error.
Source§

fn try_from(value: Any) -> Result<Self, Self::Error>

Performs the conversion.
Source§

impl<'a> TryFrom<AnyView<'a>> for Error

Source§

type Error = Error

The type returned in the event of a conversion error.
Source§

fn try_from(value: AnyView<'a>) -> Result<Self, Self::Error>

Performs the conversion.
Source§

impl TryFrom<ObjectRef> for Error

Source§

type Error = Error

The type returned in the event of a conversion error.
Source§

fn try_from(value: ObjectRef) -> Result<Self, Self::Error>

Performs the conversion.
Source§

impl TypeSubsumes<Error> for ObjectRef

Auto Trait Implementations§

§

impl Forget for Error

§

impl Freeze for Error

§

impl Move for Error

§

impl RefUnwindSafe for Error

§

impl Unpin for Error

§

impl UnsafeUnpin for Error

§

impl UnwindSafe for Error

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> AnyCompatible for T

Source§

const MATCH_ANY_EXACT: bool = const MATCH_ANY_EXACT: bool = <T as ObjectRefAnyCompatible>::MATCH_ANY_EXACT && <T::ContainerType as ObjectCore>::TYPE_FINAL;

Source§

fn match_any_exact_type_index() -> i32

Source§

unsafe fn is_undefined(field: *const T) -> bool

Whether field, which holds a value of this type or all-zero bytes, holds all-zero bytes that are no value of this type, as a null object reference, a string of type index None or a zero device type: a field that a creator left undefined for reflection to set. An undefined field is no value; a nullable reference is Option<T>, whose None is a defined value. Read more
Source§

unsafe fn copy_to_any_view(src: &T, data: &mut TVMFFIAny)

Write a cell that borrows src into data. Read more
Source§

unsafe fn move_to_any(src: T, data: &mut TVMFFIAny)

Write a cell that owns src into data. Read more
Source§

unsafe fn check_any_strict(data: &TVMFFIAny) -> bool

Whether data holds a Self as is, without conversion. Read more
Source§

unsafe fn copy_from_any_view_after_check(data: &TVMFFIAny) -> T

Copy a Self out of a cell that holds one, retaining any object. Read more
Source§

unsafe fn move_from_any_after_check(data: &mut TVMFFIAny) -> T

Move a Self out of an owning cell that holds one. Read more
Source§

unsafe fn try_cast_from_any_view(data: &TVMFFIAny) -> Result<T, ()>

Convert data into a Self by the FFI rules, such as an integer into a float; Err if it does not convert. Read more
Source§

fn get_mismatch_type_info(data: &TVMFFIAny) -> String

The name of the mismatched value data in conversion errors; by default its runtime type key.
Source§

fn type_str() -> String

The type name in conversion errors and type schemas, such as int, ffi.String or Array<int>.
Source§

fn type_schema() -> String

The type schema of the type: the JSON object that describes it, which the type schemas of functions and fields embed. Read more
Source§

fn to_any(&self) -> Any

Borrow self into an owned Any, increfing object-backed values. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> ContainerElement for T
where T: AnyCompatible,

Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T> ToString for T
where T: Display + ?Sized,

Source§

fn to_string(&self) -> String

Converts the given value to a String. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<T> TypeSubsumes<T> for T
where T: ?Sized,