dep-obj

Dependency object: effective reactive heterogeneous container.

Example: simple dependency type

The dependency objects system bases on component-arena. A component may have multiply dependency objects as its parts. Some of them may be dynamically typed and/or optional. Lets see an example of simple component with one dependency object of fixed type.

Consider as an example carriable game object Item.

To describe abstract entity Item, we will need the following list of types:

• the component data holder ItemComponent;
• the id of component Item;
• the dependency object type ItemProps;
• the components arena Items.

First, define the component containing the dependency object:

macro_attr! {
    #[derive(Debug, Component!)]
    struct ItemComponent {
        props: ItemProps,
    }
}

Then, to maintain an encapsulation, wrap Id<ItemComponent> into a newtype:

macro_attr! {
    #[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, NewtypeComponentId!)]
    pub struct Item(Id<ItemComponent>);
}

Dependency objects support properties inheritance. The tree structure of objects is defined by the DepObjId trait implementation. We do not need inheritance for Item, and we can express it and get appropriate «empty» DepObjId implementation by marking it with the DetachedDepObjId trait:

impl DetachedDepObjId for Item { }

All components need be emplaced in an appropriate arena. Lets create it:

#[derive(Debug)]
pub struct Items {
    items: Arena<ItemComponent>,
}

An another foundation the dependency object system based on is the dyn-context crate. To make Items usage more convenient it is worth to mark it as SelfState, i.e. a state containing the only one part, which is Items itself:

impl SelfState for Items { }

Now we are ready to specify the dependency type itself:

dep_type! {
    #[derive(Debug)]
    pub struct ItemProps = Item[ItemProps] {
        name: Cow<'static, str> = Cow::Borrowed(""),
        base_weight: f32 = 0.0,
        weight: f32 = 0.0,
        equipped: bool = false,
        cursed: bool = false,
    }
}

Now we have all structures encoded and can write Item methods. First, we need a way to construct a new Item:

pub fn new(state: &mut dyn State) -> Item {
    let items: &mut Items = state.get_mut();
    items.0.insert(|id| (ItemComponent { props: ItemProps::new_priv() }, Item(id)))
}

The ItemProps::new_priv is a constructor, generated by the dep_type! macro.

Next, we need a way to destroy unneeded items:

pub fn drop_self(self, state: &mut dyn State) {
    self.drop_bindings_priv(state);
    let items: &mut Items = state.get_mut();
    items.0.remove(self.0);
}

And now the last, but not least: an indirect definition of the function providing access to the dependency object in the props field:

impl_dep_obj!(Item {
    fn<ItemProps>() -> (ItemProps) { Items | .props }
});

The impl_dep_obj macro also generates the drop_bindigs_priv method we used in the drop_self method earlier.

Lets take a look at our mod items as a whole:

mod items {
    use components_arena::{Arena, Component, NewtypeComponentId, Id};
    use dep_obj::{DetachedDepObjId, dep_type, impl_dep_obj};
    use dyn_context::{SelfState, State, StateExt};
    use macro_attr_2018::macro_attr;
    use std::borrow::Cow;

    macro_attr! {
        #[derive(Debug, Component!)]
        struct ItemComponent {
            props: ItemProps,
        }
    }

    macro_attr! {
        #[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, NewtypeComponentId!)]
        pub struct Item(Id<ItemComponent>);
    }

    impl DetachedDepObjId for Item { }

    impl Item {
        pub fn new(state: &mut dyn State) -> Item {
            let items: &mut Items = state.get_mut();
            items.0.insert(|id| (ItemComponent { props: ItemProps::new_priv() }, Item(id)))
        }

        pub fn drop_self(self, state: &mut dyn State) {
            self.drop_bindings_priv(state);
            let items: &mut Items = state.get_mut();
            items.0.remove(self.0);
        }
    }

    impl_dep_obj!(Item {
        fn<ItemProps>() -> (ItemProps) { Items | .props }
    });

    #[derive(Debug)]
    pub struct Items(Arena<ItemComponent>);

    impl SelfState for Items { }

    dep_type! {
        #[derive(Debug)]
        pub struct ItemProps = Item[ItemProps] {
            name: Cow<'static, str> = Cow::Borrowed(""),
            base_weight: f32 = 0.0,
            weight: f32 = 0.0,
            equipped: bool = false,
            cursed: bool = false,
        }
    }
}

The things we lack here are Items constructor, and, unfortunately, destructor. Adding constructor is straightforward:

impl Items {
    pub fn new() -> Items {
        Items(Arena::new())
    }
}

The destructor however is tricky. The Item::drop_self method do two things: first, it drops all bindings item owes, and, second, it removes items from arena. The second thing would do automatically, but bindings require manual destroying. Thus we need explicit Items destructor to correctly drop all Items' bindings.

But we cannot just implement Drop for Items because we need State parameter to call Item::drop_bindings_priv. Unfortunately, Rust does not support a linear types concept, which would allow to have parameters in drop method. But dyn-context and components-arena crates contain some helpful things, allowing to express such type properties as good as it is possible in Rust for now.

The Arena implements special trait, Stop, that is an analogue of Drop with State parameter. Out wrap Items, however, does not implement it. Lets fix it:

#[derive(Debug, Stop)]
pub struct Items(Arena<ItemComponent>);

A thing, we want Item::stop function to do, is call drop_bindings_priv for every Item. To tell it, we need to define some struct (lets call it ItemStop), and let ItemComponent uses it to properly «stop» our Items. It is easily achieved with the Component derive macro stop parameter:

#[derive(Debug, Component!(stop=ItemStop)]
struct ItemComponent {
    props: ItemProps,
}

If we try to compile, we would get an error pointing to the fact, that the ComponentStop trait is not implemented for ItemStop. So lets implement it:

impl ComponentStop for ItemStop {
    with_arena_in_state_part!(Items);

    fn stop(&self, state: &mut dyn State, id: Id<ItemComponent>) {
        Item(id).drop_bindings_priv(state);
    }
}

Thanks to the with_arena_in_state_part macro, the only function we were need to implement manually is stop.

Take a look at out mod items:

mod items {
    use components_arena::{Arena, Component, ComponentStop, NewtypeComponentId, Id, with_arena_in_state_part};
    use dep_obj::{DetachedDepObjId, dep_type, impl_dep_obj};
    use dyn_context::{SelfState, State, StateExt, Stop};
    use macro_attr_2018::macro_attr;
    use std::borrow::Cow;

    macro_attr! {
        #[derive(Debug, Component!(stop=ItemStop))]
        struct ItemComponent {
            props: ItemProps,
        }
    }

    impl ComponentStop for ItemStop {
        with_arena_in_state_part!(Items);

        fn stop(&self, state: &mut dyn State, id: Id<ItemComponent>) {
            Item(id).drop_bindings_priv(state);
        }
    }

    macro_attr! {
        #[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, NewtypeComponentId!)]
        pub struct Item(Id<ItemComponent>);
    }

    impl DetachedDepObjId for Item { }

    impl Item {
        pub fn new(state: &mut dyn State) -> Item {
            let items: &mut Items = state.get_mut();
            items.0.insert(|id| (ItemComponent { props: ItemProps::new_priv() }, Item(id)))
        }

        pub fn drop_self(self, state: &mut dyn State) {
            self.drop_bindings_priv(state);
            let items: &mut Items = state.get_mut();
            items.0.remove(self.0);
        }
    }

    impl_dep_obj!(Item {
        fn<ItemProps>() -> (ItemProps) { Items | .props }
    });

    #[derive(Debug, Stop)]
    pub struct Items(Arena<ItemComponent>);

    impl SelfState for Items { }

    impl Items {
        pub fn new() -> Items {
            Items(Arena::new())
        }
    }

    dep_type! {
        #[derive(Debug)]
        pub struct ItemProps = Item[ItemProps] {
            name: Cow<'static, str> = Cow::Borrowed(""),
            base_weight: f32 = 0.0,
            weight: f32 = 0.0,
            equipped: bool = false,
            cursed: bool = false,
        }
    }
}

For now Item does not have any meaningful behavior. Lets add some.

pub fn new(state: &mut dyn State) -> Item {
    let items: &mut Items = state.get_mut();
    let item = items.0.insert(|id| (ItemComponent { props: ItemProps::new_priv() }, Item(id)));
    item.bind_weight(state);
    item
}

fn bind_weight(self, state: &mut dyn State) {
    let weight = Binding3::new(state, (), |(), base_weight, cursed, equipped| Some(
        if equipped && cursed { base_weight + 100.0 } else { base_weight }
    ));
    ItemProps::WEIGHT.bind(state, self, weight);
    weight.set_source_1(state, &mut ItemProps::BASE_WEIGHT.value_source(self));
    weight.set_source_2(state, &mut ItemProps::CURSED.value_source(self));
    weight.set_source_3(state, &mut ItemProps::EQUIPPED.value_source(self));
}

With the code above we have created functional dependency between four Item properties, and now weight being a function of other three properties will be updated automatically when any of them changes.

Finally, lets write some test code to make our just built game system work:

fn track_weight(state: &mut dyn State, item: Item) {
    let weight = Binding2::new(state, (), |(), name, weight: Option<Change<f32>>|
        weight.map(|weight| (name, weight.new))
    );
    weight.set_target_fn(state, (), |_state, (), (name, weight)| {
        println!("\n{name} now weights {weight}.");
    });
    item.add_binding::<ItemProps, _>(state, weight);
    weight.set_source_1(state, &mut ItemProps::NAME.value_source(item));
    weight.set_source_2(state, &mut ItemProps::WEIGHT.change_source(item));
}

fn run(state: &mut dyn State) {
    let the_item = Item::new(state);
    track_weight(state, the_item);
    ItemProps::NAME.set(state, the_item, Cow::Borrowed("The Item")).immediate();

    println!("\n> the_item.base_weight = 5.0");
    ItemProps::BASE_WEIGHT.set(state, the_item, 5.0).immediate();

    println!("\n> the_item.cursed = true");
    ItemProps::CURSED.set(state, the_item, true).immediate();

    println!("\n> the_item.equipped = true");
    ItemProps::EQUIPPED.set(state, the_item, true).immediate();

    println!("\n> the_item.cursed = false");
    ItemProps::CURSED.set(state, the_item, false).immediate();

    the_item.drop_self(state);
}

And the really last thing to do: construct State instance and call run. Our system requires State containing Items and special arena for bindings. It can be easily achieved with merge_mut_and_then method, combining two state objects into a single one. And, of course, we should not forget to call Items::stop at the end:

fn main() {
    (&mut Items::new()).merge_mut_and_then(|state| {
        run(state);
        Items::stop(state);
    }, &mut Bindings::new());
}

Example: builders

When you need to setup initial values for just constructed object, it is boring to call Type::PROP.set(state, ...).immediate() many times. The dep-obj has a tool for avoid it: object builders. It is very simple to enable it in the project:

impl Item {
    with_builder!(ItemProps);
}

This macro declares function build, which can be used in the following way:

the_item.build(state, |props| props
    .name(Cow::Borrowed("The Item"))
    .base_weight(5.0)
    .cursed(true)
);

Example: dynamically typed dependency object

Lets add some properties, which are not universal for all Items.

To do it we need to use another library: downcast-rs. Using this crate, lets define base trait for extended properties dependency type:

pub trait ItemObj: Downcast + DepType<Id=Item> { }

impl_downcast!(ItemObj);

We need a new field in the component:

macro_attr! {
    #[derive(Debug, Component!(stop=ItemStop))]
    struct ItemComponent {
        props: ItemProps,
        obj: Box<dyn ItemObj>,
    }
}

Modified Item constructor:

pub fn new(state: &mut dyn State, obj: Box<dyn ItemObj>) -> Item {
    let items: &mut Items = state.get_mut();
    let item = items.0.insert(|id| (ItemComponent {
        props: ItemProps::new_priv(),
        obj
    }, Item(id)));
    item.bind_weight(state);
    item
}

And the way to access an object (impl_dep_obj handles all dirty work including downcasting):

impl_dep_obj!(Item {
    fn<ItemProps>() -> (ItemProps) { Items | .props }
    fn<ItemObjKey>() -> dyn(ItemObj) { Items | .obj }
});

Base part is done, and we are ready to code ItemObj specific variants:

mod weapon {
    use dep_obj::dep_type;
    use dep_obj::binding::Binding3;
    use dyn_context::State;
    use crate::items::*;

    dep_type! {
        #[derive(Debug)]
        pub struct Weapon = Item[ItemObjKey] {
            base_damage: f32 = 0.0,
            damage: f32 = 0.0,
        }
    }

    impl ItemObj for Weapon { }

    impl Weapon {
        #[allow(clippy::new_ret_no_self)]
        pub fn new(state: &mut dyn State) -> Item {
            let item = Item::new(state, Box::new(Self::new_priv()));
            Self::bind_damage(state, item);
            item
        }

        fn bind_damage(state: &mut dyn State, item: Item) {
            let damage = Binding3::new(state, (), |(), base_damage, cursed, equipped| Some(
                if equipped && cursed { base_damage / 2.0 } else { base_damage }
            ));
            Weapon::DAMAGE.bind(state, item, damage);
            damage.set_source_1(state, &mut Weapon::BASE_DAMAGE.value_source(item));
            damage.set_source_2(state, &mut ItemProps::CURSED.value_source(item));
            damage.set_source_3(state, &mut ItemProps::EQUIPPED.value_source(item));
        }
    }
}