Skip to content

Entities Design Notes

Robert Jacobson edited this page Dec 5, 2025 · 13 revisions

Notes about Entity Implementation

ToDo

A few chores have been kicked down the street.

  • Check whether processing property change events in Context::set_property justifies use of small_vec or similar to prevent allocation of a Vec.
  • Add Property<E: Entity>::hash_value() in preparation for indexes
  • Make a decision either way about unsafe in entity::entity_store::get_entity_metadata_static.
  • Make a decision either way about unsafe in entity::property_store::get_property_metadata_static.
  • Add Property<E: Entity>::type_id() in preparation for indexes
  • define_derived_property! Macro rough edges:
    • allow omitting empty global properties list
    • Minimize or eliminate "type annotations needed"; rustc isn't good at inferring types for closures, which is how we supply function implementation to the macro. There are alternative patterns (e.g. passing name to macro)

smallbox Optimization Opportunities

The allocation within Context::set_property and related methods is really unfortunate. The smallbox is like Box but stores small enough values inline. (Similarly for the smallvec crate.) We should check if it's worth doing.

Issue #624.

Initialization / Registration of Properties

We still have a problem with initialization / registration of properties.

To store properties, we use a Vec<OnceCell<Box<dyn Any>>>; the OnceCell is used because we don't want to bother initializing anything for properties that are never used. Only when client code attempts to actually use a property is the OnceCell initialized.

Except what if the property is derived? It might never be used by client code, but if its dependencies change, internally ixa needs to emit a change event for the property, which means (at minimum) computing the value of the property.

  • Our current implementation calls register_property everywhere we need the property to exist. This effectively initializes all dependents of a property whenever a property is initialized.

What does it mean to "register" / "initialize" a property?

  1. Creation of a StoredPeopleProperties object (but not allocation of backing vector)
  2. Determination of is_required (by virtue of (1))
  3. Determination of dependencies and dependents
  4. Creation of Index object (but not allocation of storage for nor computation of index)
  5. Determination of is_indexed (by virtue of (4))

Observations:

  • Indexing is always deferred to the first query.
  • Allocation of storage is always done on an as-needed basis.
  • A property must be explicitly set as indexed, so (5) only actually sets the default is_indexed to false. It doesn't actually do anything. In fact, (4) is just a convenience.
  • (1) and (4) are partly about instantiating a mechanism that can perform functions on behalf of the (typed) property in a type-erased way.

Let's tease out registration/initialization that is independent of a particular Context instance vs. registration / initialization that is Context-specific.

Registry pattern

Should we replace all uses of TypeId with RegisteredItem::index()?

  • entity::entity_store::ENTITY_METADATA maps TypeId to the typle (Vec<TypeId>, Vec<TypeId>): the entity TypeId is mapped to lists of Property<E> TypeIds.

    This makes sense, because the use case is checking that a PropertyList contains all required properties, so we're checking equality of types.

  • entity::property_store::PROPERTY_METADATA maps usize to Vec<usize>: the Property::index() is mapped to a vector containing the Property::index()'s of all of that property's dependents.

    This makes sense, because the use case is looking up the properties in the property store, and they are addressable via the index.

Integration with Context

API on Context

Should add_entity<E: Entity> return a Result<EntityId<E>, IxaError>? Right now it fails only if InitializationList is invalid.

pub fn add_entity<E: Entity, PL: PropertyList<E>>(&mut self, property_list: PL) -> Result<EntityId<E>, IxaError>;
  • Makes sense to return a Result if we let user add an entity, say, at debug console or via web API.
  • Makes sense to just panic if we only care about calling the method from client code directly.

Should EntityStore / PropertyStore be fields of Context?

Arguments for making the EntityStore and PropertyStore fields of Context:

  • Not every subsystem cares about entities/properties, but a lot of them do. (PluginContext defines the minimal interface all DataPlugins can assume exists. Half of the trait extension constraints in PluginContext are related to PeopleContext.)
  • Accesses to these stores are often in the hottest paths / tightest loops, which recommends minimizing indirection (one fewer pointer dereference)

Arguments against making the EntityStore and PropertyStore fields of Context:

  • Historically the only intrinsic properties and functions of the concrete Context type is managing the timeline (events and plans). All other functionality is (was) provided by plugins. Adding entities (EntityStore and PropertyStore) to Context expands its responsibilities from "events that happen in time" to also include "state of the world". Philosophically, one could argue this violates the "separation of concerns" / "single responsibility" principle. (Counterargument: A good software engineer is not constrained by rules of thumb.)
  • Is the indirection required for accessing a DataPlugin even measurable?

Types

struct EntityId<E: Entity>(usize, PhantomData<E>)

  • The entity ID should know the Entity type so that a PersonId can't be used as a SettingId.
  • The original PersonId type is opaque–it cannot be created or destructured outside of the ixa crate. To achieve the same thing, we do this: EntityId<E: Entity>(usize, PhantomData<E>)
  • Entity cannot store the entity count, because we don't want client code to be able to create a new entity (or modify the entity count), and the Entity types are implemented in client code. So we store the entity count in the EntityStore.

Properties

Required versus Explicit

Originally it appears we assumed that it is not possible to have a non-required property without a default value. (I think we just let an internal unwrap fail.) Should we enforce this in the macro implementations? (Related to the next section as well.)

Right now we store: Vec<Option<Property>>

But maybe we should only store: Vec<Property>

If the value is allowed to be not set, it should be an Option<Property>. The difference is, do we enforce this at the API level, or do we make client code deal with it?

Semantics of Property Change

  • If you try to set a property to the value it already has, is a property change event emitted? (Previously, yes.)
  • If you try to set an unset property to its default value, is a property change event emitted? (Previously, yes.)

I think we emit a property change even unconditionally, because it was hard to keep track of whether derived properties actually changed value due to type erasure. And since we emit an event for derived properties, we also do so for non-derived properties.

EDIT: There doesn't seem to be strong opinions about this either way, but there's consensus that it's not much of a burden on client code to do a check. Because a change event already isn't reporting on the instantaneous state of the world but rather a report of a particular transaction, it's already incumbant on client code to check whether the event is actionable.

See PropertyValueStore::replace().

Also: Previously, it appears we assumed that it is not possible to have a non-required property without a default value.

General Stuff

Internal checks

There are several places in ixa internals where we have checks for things that should never happen unless there's a bug in ixa itself. These checks could be conditionally removed depending on the build profile:

#[inline(always)]
fn expect_debug_only<T>(opt: Option<T>, msg: &str) -> T {
    if cfg!(debug_assertions) {
        opt.expect(msg)
    } else {
        unsafe { opt.unwrap_unchecked() }
    }
}

// or the plain vanilla inline version:
let value = if cfg!(debug_assertions) {
  property_store
          .get(entity_id)
          .expect("getting a property value with \"constant\" initialization should never fail")
} else {
  unsafe { property_store.get(entity_id).unwrap_unchecked() }
};

The actual performance impact of this is probably negligible. It might be worth running some experiments to see if it's worth it.

define_rng! macro

We have this "rng_name_duplication_guard_" thing that I don't understand. Some research shows it was a pre-Rust 2018 hack to prevent global singletons with the same name.

  • It doesn't work anymore (maybe?).
  • Why not have RNGs with the same name?
  • The macro makes the RNG private, so it's not accessible outside of the module anyway.

Alternatives (that I am also suspicious of):

  1. Just remove it. We trust client code to know how to refer to the correct symbol in other places.
  2. "private trait" trick:
$crate::paste::paste! {
    trait [<__rng_guard_ $random_id>] {}
    impl [<__rng_guard_ $random_id>] for () {}
}
  1. unique const generic:
struct __RngNameDupGuard<const NAME: &'static str>;
type _ = __RngNameDupGuard<{ stringify!($random_id) }>;

Visibility of Synthesized types

We synthesize these types with macros without a pub visibility (or any other visibility).

  • DataPlugin
  • RNGs
  • Entity
  • Property<E: Entity>

Clone this wiki locally