Repository navigation
Entities Design Notes
A few chores have been kicked down the street.
- Check whether processing property change events in
Context::set_propertyjustifies use ofsmall_vecor similar to prevent allocation of aVec. - Add
Property<E: Entity>::hash_value()in preparation for indexes - Make a decision either way about
unsafeinentity::entity_store::get_entity_metadata_static. - Make a decision either way about
unsafeinentity::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)
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.
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_propertyeverywhere 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?
- Creation of a
StoredPeoplePropertiesobject (but not allocation of backing vector) - Determination of
is_required(by virtue of (1)) - Determination of dependencies and dependents
- Creation of
Indexobject (but not allocation of storage for nor computation of index) - 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_indexedtofalse. 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.
Should we replace all uses of TypeId with RegisteredItem::index()?
-
entity::entity_store::ENTITY_METADATAmapsTypeIdto the typle(Vec<TypeId>, Vec<TypeId>): the entityTypeIdis mapped to lists ofProperty<E>TypeIds.This makes sense, because the use case is checking that a
PropertyListcontains all required properties, so we're checking equality of types. -
entity::property_store::PROPERTY_METADATAmapsusizetoVec<usize>: theProperty::index()is mapped to a vector containing theProperty::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.
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
Resultif 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.
Arguments for making the EntityStore and PropertyStore fields of Context:
- Not every subsystem cares about entities/properties, but a lot of them do.
(
PluginContextdefines the minimal interface allDataPlugins can assume exists. Half of the trait extension constraints inPluginContextare related toPeopleContext.) - 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
Contexttype is managing the timeline (events and plans). All other functionality is (was) provided by plugins. Adding entities (EntityStoreandPropertyStore) toContextexpands 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
DataPlugineven measurable?
- The entity ID should know the
Entitytype so that aPersonIdcan't be used as aSettingId. - The original
PersonIdtype is opaque–it cannot be created or destructured outside of theixacrate. To achieve the same thing, we do this:EntityId<E: Entity>(usize, PhantomData<E>) -
Entitycannot 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 theEntitytypes are implemented in client code. So we store the entity count in theEntityStore.
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?
- 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.
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.
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):
- Just remove it. We trust client code to know how to refer to the correct symbol in other places.
- "private trait" trick:
$crate::paste::paste! {
trait [<__rng_guard_ $random_id>] {}
impl [<__rng_guard_ $random_id>] for () {}
}- unique
constgeneric:
struct __RngNameDupGuard<const NAME: &'static str>;
type _ = __RngNameDupGuard<{ stringify!($random_id) }>;We synthesize these types with macros without a pub visibility (or any other visibility).
DataPlugin- RNGs
EntityProperty<E: Entity>