Skip to main content

Crate tvm_ffi

Crate tvm_ffi 

Source
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.String holds UTF-8, so String::as_str does 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 TensorView received as a function argument is valid only during the call, and so is an Any holding a DLTensor* converted from it or from an AnyView.
  • 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
Any and AnyView: owned and borrowed type-erased FFI values.
big_int
Integers with inline i64 storage and arbitrary-precision arithmetic.
collections
Containers shared across languages: Array, List, Map, Shape and Tensor.
derive
The derive macros of object types and object references.
device
The device stream of the FFI environment: current_stream and with_stream.
dtype
Data types: DLDataTypeExt and 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. EnumRef looks values up; reflection::EnumDef registers them.
error
Error, the error that crosses the FFI boundary, and its ErrorKinds.
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 with TypeAttrDef and enum values with EnumDef; call the typed hooks that attributes hold with NativeFunction.
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
String and Bytes, 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 Err result, and pass an Ok through.
bail
Return an Error of a kind with a formatted message from the current function.
cached_field_getter
Resolve a reflected field of the object type N once, and keep its getter for the process: a &'static FieldGetter<N>.
cached_global_func
Look up a registered global Function by name once, and keep it for the process: a &'static Function.
ensure
Return an Error from the current function unless a condition holds.
format_err
Make an Error of a kind with a formatted message, recording the source location in the backtrace, as bail! does without returning.
impl_any_compatible_conversions
Implement the conversions between each listed AnyCompatible type and FFI values: TryFrom<AnyView>, TryFrom<Any> and TryFrom<&Any>, and use as an argument of Function::call_tuple and of functions from into_typed_fn!.
impl_object_ref_downcast_ref
Implement the in-place downcast_ref borrows (array[i], Any::downcast_ref, ObjectRefCore::downcast_ref) for each listed object reference type. #[derive(ObjectRef)] emits it; a reference that implements ObjectRefCore by 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> and From<&Source> into Target, AsRef<Target>, which borrows a &Source as &Target without touching the reference count, and IntoArg<Target> for Source and &Source, and TypeSubsumes<Source> for Target, so Array::upcast turns an Array<Source> into an Array<Target>. It also implements the strict downcast back, TryFrom<Target> and TryFrom<&Target> for Source, which return a TypeError naming both types.
into_typed_fn
Wrap a Function as 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 match matches 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 returns Result<()>: 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 ; returns Ok(()); one that ends in an expression returns it, a Result<()>.
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_DOC does

Structs§

DLDataType
DLPack data type struct
DLDevice

Enums§

DLDataTypeCode
DLPack data type code enum
DLDeviceType
TypeIndex
The index type of the FFI objects

Attribute Macros§

dispatch
Generate runtime type dispatch from the prefix_* methods of an impl.
rs_object
Define an object type in Rust that every language can use.