Late Struct

Late-bound structure definitions.

This crate exposes the late_struct! macro, which defines a structure whose set of fields can be extended by any crate within a compiled artifact using the late_field! macro. Unlike regular structures, dependents on the crate which originally defined the structure are allowed to extend it. Additionally, the structure we defined can be instantiated in any crate using a LateInstance, even if dependents of that crate are still extending it.

Basic Usage

For example, let's say we had a crate hierarchy where "dependent depends on dependency."

In dependency, we could define a new late-struct marker using the late_struct! macro...

use late_struct::late_struct;

// Marker type for our application context.
// Any type could be used here.
pub struct AppContext;

late_struct!(AppContext);

...and then, in dependent, we could proceed to add a field to it using the late_field! macro:

use late_struct::late_field;

use dependency::AppContext;

pub struct MyField(Vec<u32>);

late_field!(MyField[AppContext]);

...just note that, by default, the field value must implement Debug, Default, and live for 'static.

We can then refer to the structure we've created with a LateInstance. For example, back in dependency, we can write...

use late_struct::LateInstance;

pub fn create_my_instance() -> LateInstance<AppContext> {
    LateInstance::new()
}

...even though downstream crates such as dependent are still adding fields to it. Finally, we can access fields using the LateInstance::get and LateInstance::get_mut methods. For example, in the dependent crate, we could write...

use dependency::{AppContext, create_my_instance};

pub fn example() {
    let mut instance = create_my_instance();

    instance.get_mut::<MyField>().0.push(1);
    instance.get_mut::<MyField>().0.push(2);
    instance.get_mut::<MyField>().0.push(3);

    eprintln!("Our numbers are {:?}", instance.get::<MyField>());
}

See the documentation of LateInstance for more ways to access the instance.

Note that the "key type" used to refer to a given field can be distinct from its value type. For example, in the previous snippet, we could make MyField a zero-sized marker type and set it up to refer to a value of type Vec<u32> instead. We do this by changing our late_field! macro invocation like so...

use dependency::{AppContext, create_my_instance};

// The `#[non_exhaustive]` attribute helps ensure that other crates don't
// accidentally try to instantiate what should just be a marker type.
pub struct MyField;

late_field!(MyField[AppContext] => Vec<u32>);
//                              ^^^^^^^^^^^ this is how we specify the
//                                          field's value type explicitly.

pub fn example() {
    let mut instance = create_my_instance();

    // Notice that we're now accessing the `&mut Vec<u32>` directly
    // rather than the `MyField` wrapper.
    instance.get_mut::<MyField>().push(1);
    instance.get_mut::<MyField>().push(2);
    instance.get_mut::<MyField>().push(3);

    eprintln!("Our numbers are {:?}", instance.get::<MyField>());
}

Advanced Usage

By default, all fields of a given struct are required to implement Debug, Default, and 'static. These requirements, however, can be changed on a per-struct basis. For instance, we can remove the Debug requirement and instead require Send, Sync, and a custom trait Reflect with the following late_struct! definition...

use late_struct::late_struct;

trait Reflect {
    fn say_hi(&self);
}

struct MyStruct;

late_struct!(MyStruct => dyn 'static + Reflect + Send + Sync);
//                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
//                    field value types must upcast to this type

The only mandatory trait bounds on a field are that it have a Default initializer, be Sized, and live for 'static.

We can then enumerate these fields at runtime using the LateInstance::fields method and access those fields' erased values using the LateInstance::get_erased, and LateInstance::get_erased_mut methods like so...

struct MyField;

impl Reflect for MyField {
   fn say_hi(&self) {
       println!("Hello!");
   }
}

late_field!(MyField[MyStruct]);

fn say_greetings_on_a_thread(instance: Arc<LateInstance<MyStruct>>) {
    std::thread::spawn(move || {
        for field in instance.fields() {
             instance.get_erased(field).say_hi();
        }
    })
    .join()
    .unwrap()
}

Struct members can also be made to satisfy non-dyn compatible standard traits such as Eq, Hash, and Clone by making the members implement the DynEq, DynHash, and DynClone traits respectively. This lets us write, for instance...

use std::{fmt::Debug, collections::HashSet};
use late_struct::{late_field, late_struct, DynEq, DynHash, DynClone, LateInstance};

trait MyStructMember: Debug + DynEq + DynHash + DynClone {}

impl<T> MyStructMember for T
where
    T: Debug + DynEq + DynHash + DynClone,
{
}

struct MyStruct;

late_struct!(MyStruct => dyn MyStructMember);

struct MyField(u32);

late_field!(MyField[MyStruct]);

fn demo() {
    // The struct implements `Default`...
    let my_instance = LateInstance::<MyStruct>::default();

    // ...debug...
    eprintln!("{my_instance:?}");

    // ...clone...
    let my_instance_2 = my_instance.clone();

    // ...eq...
    assert_eq!(my_instance, my_instance_2);

    // ...and hash!
    let mut map = HashSet::new();

    assert!(map.insert(my_instance));
    assert!(!map.insert(my_instance_2));
}

Internals

Internally, each field we define with late_field! creates a static containing a LateFieldDescriptor and uses linkme (or inventory on WebAssembly) to add it to a global list of all fields in the crate. When our first LateInstance is instantiated, all these LateFieldDescriptors are collected and laid out into a structure at runtime, with each fields' offset being written back into an AtomicUsize in the LateFieldDescriptor.

From there, structure instantiation and field fetching work more-or-less like they would with a regular structure. LateInstance creates one big heap allocation for the structure it represents and initializes each field accordingly. To access a field, all we have to do is offset the structure's base pointer by the dynamically-initialized offset stored in the field's LateFieldDescriptor, making field accesses extremely cheap.

Many of these internals are exposed to the end user. See LateStructDescriptor and LateFieldDescriptor (which you can obtain from the LateStruct::descriptor and LateField::descriptor methods respectively) to learn about various options for reflecting upon the layout of a structure.

Contributing

Contributions in any form (issues, pull requests, etc.) to this project must adhere to Rust's Code of Conduct.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in late-struct by you shall be licensed as below, without any additional terms or conditions.

License

This project is licensed under the MIT License.