Crate vtable

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 to std::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

• new_vref
  Creates a VRef or a VRefMut suitable for an instance that implements the trait

Structs

• Dyn
  This is a marker type to be used in VRc and VWeak to mean that the actual type is not known.
• Layout
  Similar to core::alloc::Layout, but repr(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 where VTable is a VTable struct, and X is the type of the instance, or Dyn if it is not known
• VWeakMapped
  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

• HasStaticVTable
  Allow to associate a VTable with a type.
• VTableMeta
  Internal trait that is implemented by the #[vtable] macro.
• VTableMetaDrop
  This trait is implemented by the #[vtable] macro.
• VTableMetaDropInPlace
  This trait is implemented by the #[vtable] macro.

Attribute Macros

• vtable
  This macro needs to be applied to a VTable structure