Expand description
Rust bindings of TVM FFI, the open ABI and FFI for machine learning systems.
Values cross the boundary as Any and AnyView. Objects, such as
Array, Map, Tensor and types defined with rs_object, are
reference counted and shared with C++ and Python. A Function is
callable from every language, and an Error raised in one arrives in
the others.
§Examples
use tvm_ffi::{Array, Function, Result};
let sum = |xs: Array<i64>| -> Result<i64> { Ok(xs.iter().sum()) };
Function::register_global_typed("my_ext.sum", sum, "Sum the elements.")?;
let sum = Function::get_global("my_ext.sum")?;
let total = sum.call_tuple((Array::from_vec(vec![1_i64, 2, 3]),))?;
assert_eq!(i64::try_from(total)?, 6);§FFI contracts
Some guarantees rest on contracts every language keeps, which Rust cannot check:
- An
ffi.Stringholds UTF-8, soString::as_strdoes not validate it. - Types, functions and attributes register during static initialization,
such as in a
static_init_block!, before other threads read them: readers of the runtime’s tables take no lock. - A type key describes the same type in every library that declares it;
see
rs_object. - A
TensorViewreceived as a function argument is valid only during the call, and so is anAnyholding aDLTensor*converted from it or from anAnyView. - A registered structural visit or mutate hook uses the visitor or mutator only through its arguments, during the call, and does not keep it.
Re-exports§
pub use crate::any::Any;pub use crate::any::AnyView;pub use crate::big_int::BigInt;pub use crate::collections::array::Array;pub use crate::collections::list::List;pub use crate::collections::map::Map;pub use crate::collections::shape::Shape;pub use crate::collections::tensor::Tensor;pub use crate::collections::tensor::TensorView;pub use crate::dtype::DLDataTypeExt;pub use crate::enum_ref::EnumRef;pub use crate::error::ATTRIBUTE_ERROR;pub use crate::error::INDEX_ERROR;pub use crate::error::INTERNAL_ERROR;pub use crate::error::KEY_ERROR;pub use crate::error::OVERFLOW_ERROR;pub use crate::error::RUNTIME_ERROR;pub use crate::error::TYPE_ERROR;pub use crate::error::VALUE_ERROR;pub use crate::error::ZERO_DIVISION_ERROR;pub use crate::error::Error;pub use crate::error::ErrorKind;pub use crate::error::Result;pub use crate::extra::dispatch::Dispatcher;pub use crate::extra::dispatch::IntoDispatcher;pub use crate::extra::module::Module;pub use crate::extra::structural_eq_hash::StructuralOptions;pub use crate::extra::structural_eq_hash::get_first_structural_mismatch;pub use crate::extra::structural_eq_hash::get_first_structural_mismatch_with;pub use crate::extra::structural_eq_hash::structural_equal;pub use crate::extra::structural_eq_hash::structural_equal_with;pub use crate::extra::structural_eq_hash::structural_hash;pub use crate::extra::structural_eq_hash::structural_hash_with;pub use crate::extra::structural_map::structural_map;pub use crate::extra::structural_mutate::InplaceMode;pub use crate::extra::structural_mutate::MutationView;pub use crate::extra::structural_mutate::StructuralMutatorView;pub use crate::extra::structural_mutate::structural_mutate;pub use crate::extra::structural_visit::DefRegionKind;pub use crate::extra::structural_visit::StructuralVisitorView;pub use crate::extra::structural_visit::VisitInterrupt;pub use crate::extra::structural_visit::structural_visit;pub use crate::extra::structural_walk::IntoWalkResult;pub use crate::extra::structural_walk::WalkOrder;pub use crate::extra::structural_walk::WalkResult;pub use crate::extra::structural_walk::structural_walk;pub use crate::extra::unchanged::Unchanged;pub use crate::extra::unchanged::UnchangedOr;pub use crate::function::Function;pub use crate::object::Object;pub use crate::object::ObjectArc;pub use crate::object::ObjectCore;pub use crate::object::ObjectRef;pub use crate::object::ObjectRefCore;pub use crate::optional::Optional;pub use crate::static_init::run_static_init_blocks;pub use crate::string::Bytes;pub use crate::string::String;pub use crate::type_traits::AnyCompatible;pub use crate::type_traits::IntoArg;pub use tvm_ffi_sys;
Modules§
- any
AnyandAnyView: owned and borrowed type-erased FFI values.- big_int
- Integers with inline
i64storage and arbitrary-precision arithmetic. - collections
- Containers shared across languages:
Array,List,Map,ShapeandTensor. - derive
- The derive macros of object types and object references.
- device
- The device stream of the FFI environment:
current_streamandwith_stream. - dtype
- Data types:
DLDataTypeExtand the Rust element types of tensors. - enum_
ref - Enums shared across languages: each value is a named singleton of an
object type whose parent is
EnumObj.EnumReflooks values up;reflection::EnumDefregisters them. - error
Error, the error that crosses the FFI boundary, and itsErrorKinds.- extra
- Runtime type dispatch, structural traversals (
structural_walk,structural_visit,structural_mutate,structural_map) and modules. - function
Function, a callable shared with C++ and Python, and the global function registry.- object
- Objects: reference-counted values shared with C++ and Python, and the
traits that define object types (
ObjectCore) and their managed references (ObjectRefCore). - optional
Optional<T>, an optional value that is not an object, such as a scalar or a string, stored in place.- reflection
- Object reflection: look up the methods, fields and type attributes of
registered types; register Rust object types with
ObjectDef, type attributes withTypeAttrDefand enum values withEnumDef; call the typed hooks that attributes hold withNativeFunction. - rvalue_
ref RValueRef, an object argument whose reference the callee may take over.- static_
init - Static init blocks: code that runs when the program or library that holds it loads. The
blocks of a program or library are gathered at link time, wherever in it they are, and a
constructor runs them when it loads. Once Python loads a library built on this crate, by any
means, it sees what the blocks registered, such as global functions. A block that several
libraries of a process have, as each links its own copy of a crate they share, runs once. See
static_init_block!. - string
StringandBytes, immutable reference-counted strings.- type_
traits - Traits that map Rust types to TVM-FFI values.
Macros§
- attach_
context - Append the current source location to the backtrace of an
Errresult, and pass anOkthrough. - bail
- Return an
Errorof a kind with a formatted message from the current function. - cached_
field_ getter - Resolve a reflected field of the object type
Nonce, and keep its getter for the process: a&'static FieldGetter<N>. - cached_
global_ func - Look up a registered global
Functionby name once, and keep it for the process: a&'static Function. - ensure
- Return an
Errorfrom the current function unless a condition holds. - format_
err - Make an
Errorof a kind with a formatted message, recording the source location in the backtrace, asbail!does without returning. - impl_
any_ compatible_ conversions - Implement the conversions between each listed
AnyCompatibletype and FFI values:TryFrom<AnyView>,TryFrom<Any>andTryFrom<&Any>, and use as an argument ofFunction::call_tupleand of functions frominto_typed_fn!. - impl_
object_ ref_ downcast_ ref - Implement the in-place
downcast_refborrows (array[i],Any::downcast_ref,ObjectRefCore::downcast_ref) for each listed object reference type.#[derive(ObjectRef)]emits it; a reference that implementsObjectRefCoreby hand calls it. - impl_
object_ ref_ upcast - Implement zero-copy conversions from a derived object reference to one of
its base object-reference types:
From<Source>andFrom<&Source>intoTarget,AsRef<Target>, which borrows a&Sourceas&Targetwithout touching the reference count, andIntoArg<Target>forSourceand&Source, andTypeSubsumes<Source>forTarget, soArray::upcastturns anArray<Source>into anArray<Target>. It also implements the strict downcast back,TryFrom<Target>andTryFrom<&Target>forSource, which return aTypeErrornaming both types. - into_
typed_ fn - Wrap a
Functionas a typed closure with the given signature:into_typed_fn!(func, Fn(A, B) -> Result<R>). - match_
any - Match the runtime type of a value, the way
matchmatches an enum. - static_
init_ block - Run code when the program or library that holds it loads, the Rust form of
TVM_FFI_STATIC_INIT_BLOCK. The body is the body of a function that returnsResult<()>: it registers what the library defines, such as global functions, and stops at its first error, which?returns. A body whose statements all end in;returnsOk(()); one that ends in an expression returns it, aResult<()>. - tvm_
ffi_ dll_ export_ typed_ func - Macro to export a typed function as a C symbol that follows the tvm-ffi ABI
- tvm_
ffi_ dll_ export_ typed_ func_ doc - Macro to export the doc string of a function exported with
tvm_ffi_dll_export_typed_func!, as C++TVM_FFI_DLL_EXPORT_TYPED_FUNC_DOCdoes
Structs§
- DLData
Type - DLPack data type struct
- DLDevice
Enums§
- DLData
Type Code - DLPack data type code enum
- DLDevice
Type - Type
Index - The index type of the FFI objects