Crate vtable_gen
source ·Expand description
§VTable Gen
This crate provides macros to generate C++-ABI VTables by defining the structure and vtable layout. It also supports VTable inheritance and basic class inheritance.
§Examples
Check out tests.rs
, which is pretty self-explanatory.
§Usage
§Base Structs
- Define a structure that contains virtual functions
- Define a structure for the VTable that exactly matches the name of the structure it belongs to,
followed by
VTable
exactly. Example:
struct Foo {}
struct FooVTable {}
- Mark both the VTable and structure with
#[gen_vtable]
. Any function pointers you include in the VTable struct will require implementation in an automatically-generated<name>Virtuals
trait. Complete Example:
#[gen_vtable]
struct Foo {}
#[gen_vtable]
struct FooVTable {
foo: extern "C" fn(this: &Foo) -> u32;
}
impl FooVirtuals for Foo {
extern "C" fn foo(this: &Foo) -> u32 { todo!() }
}
§Derived Structs
- Define structures exactly as with base structures
- Include the attribute
base
. Example:
#[gen_vtable]
struct Foo {}
#[gen_vtable]
struct FooVTable {}
#[gen_vtable(base = "Foo")]
struct Bar {}
#[gen_vtable(base = "Foo")]
struct BarVTable {}
§Constructing Structs with VTables
Constructing structs with VTables is easy. If the struct is default-able, simply derive
DefaultVTable
instead of Default
. This will impl Default
. If the struct isn’t default-able,
define some function fn new(/* args */) -> Self
. Mark the function with new_with_vtable
,
supplying base structs if necessary as in Derived Structs
. For the compiler to know the type,
you must either explicitly replace Self
as the return type with the type itself, or specify
self_type
. Here’s a verbose example:
// ...
impl Bar {
#[new_with_vtable(self_type = "Bar")]
fn new(baz: u32) -> Self {
Self { baz }
}
}
which is also equivalent to
// ...
impl Bar {
#[new_with_vtable]
fn new(baz: u32) -> Bar {
Self { baz }
}
}
If there is a base struct that requires its new
function to be called, you will have to also
explicitly initialize a base_with_vtable
member with the new
constructor of the child type.
For example:
// ...
impl Bar {
#[new_with_vtable(base = "Foo", self_type = "Bar")]
fn new(baz: u32) -> Self {
Self {
base_with_vtable: Foo::new(123),
baz
}
}
}
§Overriding Functions
Overriding functions is easy. Because all functions are defined in Traits, one can specify for the
compiler to not generate implementations for base struct Virtuals
with the argument no_base_trait_impl
on the VTable (or both for symmetry :)).
Example:
// ...
#[gen_vtable(base = "Foo", no_base_trait_impl)]
struct BarVTable {}
// ...
impl FooVirtuals for Bar {
extern "C" fn some_fn(this: &Foo) {
// ...
}
}
The only caveat is you will have to implement all base traits.
§Automatic Implementation
For an automatic implementation, in the case of some abstract struct for example, simply supply unimpl
as an argument to gen_vtable
, and all methods will be implemented with unimplemented!()
. Example:
// ...
#[gen_vtable(unimpl)]
struct Foo {}
#[gen_vtable(unimpl)]
struct FooVTable {}
// `FooVirtuals` is implemented for `Foo`
§Known Limitations
vtable_gen
currently does not support generic structs. This is a trivial addition, however, and will likely be added in the future
Macros§
- Generates a VTable member for a struct, or a trait if the struct is a vtable. See examples.