Expand description
This crate allows you to create ffi-friendly virtual tables.
§Features
- A
#[vtable]
macro to annotate a VTable struct to generate the traits and structure to safely work with it. VRef
/VRefMut
/VBox
types. They are fat reference/box types which wrap a pointer to the vtable, and a pointer to the object.VRc
/VWeak
types: equivalent tostd::rc::{Rc, Weak}
types but works with a vtable pointer.- Ability to store constants in a vtable.
- These constants can even be a field offset.
§Example of use:
use vtable::*;
// we are going to declare a VTable structure for an Animal trait
#[vtable]
#[repr(C)]
struct AnimalVTable {
/// pointer to a function that makes a noise. The `VRef<AnimalVTable>` is the type of
/// the self object.
///
/// Note: the #[vtable] macro will automatically add `extern "C"` if that is missing.
make_noise: fn(VRef<AnimalVTable>, i32) -> i32,
/// if there is a 'drop' member, it is considered as the destructor.
drop: fn(VRefMut<AnimalVTable>),
}
struct Dog(i32);
// The #[vtable] macro created the Animal Trait
impl Animal for Dog {
fn make_noise(&self, intensity: i32) -> i32 {
println!("Wof!");
return self.0 * intensity;
}
}
// the vtable macro also exposed a macro to create a vtable
AnimalVTable_static!(static DOG_VT for Dog);
// with that, it is possible to instantiate a VBox
let animal_box = VBox::<AnimalVTable>::new(Dog(42));
assert_eq!(animal_box.make_noise(2), 42 * 2);
The #[vtable]
macro created the “Animal” trait.
Note that the #[vtable]
macro is applied to the VTable struct so
that cbindgen
can see the actual vtable.
Re-exports§
pub use const_field_offset::*;
Macros§
Structs§
- Dyn
- This is a marker type to be used in
VRc
andVWeak
to mean that the actual type is not known. - Layout
- Similar to
core::alloc::Layout
, butrepr(C)
- VBox
- An equivalent of a Box that holds a pointer to a VTable and a pointer to an instance. A VBox frees the instance when dropped.
- VOffset
- Represents an offset to a field of type matching the vtable, within the Base container structure.
- VRc
- A reference counted pointer to an object matching the virtual table
T
- VRcMapped
- VRcMapped allows bundling a VRc of a type along with a reference to an object that’s
reachable through the data the VRc owns and that satisfies the requirements of a Pin.
VRCMapped is constructed using
VRc::map
and, like VRc, has a weak counterpart,VWeakMapped
. - VRef
VRef<'a MyTraitVTable>
can be thought as a&'a dyn MyTrait
- VRefMut
VRefMut<'a MyTraitVTable>
can be thought as a&'a mut dyn MyTrait
- VWeak
- Weak pointer for the
VRc
whereVTable
is a VTable struct, andX
is the type of the instance, orDyn
if it is not known - VWeak
Mapped - VWeakMapped allows bundling a VWeak with a reference to an object that’s reachable
from the object a successfully upgraded VWeak points to. VWeakMapped’s API consists
only of the ability to create clones and to attempt upgrading back to a
VRcMapped
.
Traits§
- HasStaticV
Table - Allow to associate a VTable with a type.
- VTable
Meta - Internal trait that is implemented by the
#[vtable]
macro. - VTable
Meta Drop - This trait is implemented by the
#[vtable]
macro. - VTable
Meta Drop InPlace - This trait is implemented by the
#[vtable]
macro.
Attribute Macros§
- vtable
- This macro needs to be applied to a VTable structure