Module people

A generic mechanism for representing people and associated data.

We have a set of people indexed by PersonId and then each person can have an arbitrary number of person properties PersonProperty, which are values keyed by a type. Person properties are defined with a macro (define_person_property!() or define_person_property_with_default!())

Initializing Person Properties

Person properties can have their initial values set in several ways:

• An initial value can be provided at person creation time in Context::add_person().
• The property can have a default value (provided when the property is defined.)
• The property can have an initializer function (provided when the property is defined) that is called lazily when the property is first accessed.

If neither a default or an initializer is provided, then you must provide an initial value for each person on person creation. Failure to do so will generally cause failure of Context::add_person().

Setting Person Properties

Properties can also have their values changed with Context::set_person_property(). If the property is not initialized yet, this will implicitly call the initializer (or set the default) and then reset the value.

Derived Properties

It is also possible to have a “derived property” whose value is computed based on a set of other properties. When a derived property is defined, you must supply a function that takes the values for those dependencies and computes the current value of the property. Note that this function cannot access the context directly and therefore cannot read any other properties. It also should have a consistent result for any set of inputs, because it may be called multiple times with those inputs, depending on the program structure.

Change Events

Whenever a person property E has potentially changed, either because it was set directly or because it is a derived property and one of its dependencies changed, a PersonPropertyChangeEvent<E> will be emitted. Note that Ixa does not currently check that the new value is actually different from the old value, so calling Context::set_person_property() will always emit an event. Initialization is not considered a change, but Context::set_person_property() on a lazily initialized event will emit an event for the change from the initialized value to the new value.

Querying

Person properties provides an interface to query for people matching a given set of properties. The basic syntax is to supply a set of (property, value) pairs, like so query_people(((Age, 30), (Gender, Female))). Note that these need to be wrapped in an extra set of parentheses to make them a single tuple to pass to Context::query_people(). Queries implement strict equality, so if you want a fancier predicate you need to implement a derived property that computes it and then query over the derived property.

The internals of query are deliberately opaque in that Ixa may or may not ordinarily choose to create caches or indexes for queries. However, you force an index to be created for a single property by using Context::index_property().

Re-exports

• pub use data::PersonPropertyHolder;

Macros

• define_derived_property
  Defines a derived person property with the following parameters:
• define_person_property
  Defines a person property with the following parameters:
• define_person_property_with_default
  Defines a person property with the following parameters:

Structs

• PersonCreatedEvent
  Emitted when a new person is created These should not be emitted outside this module
• PersonId
  Represents a unique person.
• PersonPropertyChangeEvent
  Emitted when a person property is updated These should not be emitted outside this module
• QueryAnd
  Helper utility for combining two queries, useful if you want to iteratively construct a query in multiple parts.

Traits

• ContextPeopleExt
  A trait extension for Context that exposes the people functionality.
• InitializationList
  A trait that contains the initialization values for a new person. Do not use this directly, but instead use the tuple syntax.
• PersonProperty
  An individual characteristic or state related to a person, such as age or disease status.
• Query
  Encapsulates a person query.