Module triggers 

Trigger criteria that emit user-defined events.

A trigger is a way to say: when some simulation criterion is met, emit a concrete user-defined IxaEvent. Trigger-emitted events are ordinary Ixa events, so any number of subscribers can listen for them with Context::subscribe_to_event.

A trigger criterion is not itself registered on a context. A criterion, such as PropertyChangeTrigger or TimeTrigger, defines what should be monitored. A complete trigger is created only after binding that criterion to a concrete event with one of the emit_* methods. The value returned by emit_with, emit_value, or emit_default is the value passed to ContextTriggersExt::register_trigger.

The usual flow is:

1. Choose one of the built-in trigger criteria.
2. Bind it to the event you want emitted with TriggerCriterion::emit_with, TriggerCriterion::emit_value, or TriggerCriterion::emit_default.
3. Register the complete trigger with ContextTriggersExt::register_trigger.
4. Subscribe to the emitted user event as usual.

TogglingTrigger is a composite trigger for stateful on/off behavior. Instead of binding a single criterion to a single event, it combines an activation criterion and a deactivation criterion, each with its own emitted event (of possibly distinct types).

The usual flow for a toggling trigger is:

1. Choose the activation and deactivation criteria.
2. Pair them with TogglingTriggerCriteria::new.
3. Bind the pair to activation and deactivation events with one of the TogglingTriggerCriteria::emit_* methods.
4. Register the complete trigger with ContextTriggersExt::register_trigger.
5. Subscribe to the activation and deactivation events as usual.

Construct an event from observation data

Each trigger criterion has its own observation data type, available as the criterion’s TriggerCriterion::Observation associated type. For example, PropertyChangeTrigger observations use PropertyChangeTriggerEvent containing the entity ID and the previous and current property values. EntityCountTrigger, PropertyValueCountTrigger, TimeTrigger, and PeriodicTimeTrigger use their corresponding *TriggerEvent types.

For events that do not need observation data, use TriggerCriterion::emit_value to emit a constant event value, or TriggerCriterion::emit_default when the event type implements Default.

Use TriggerCriterion::emit_with when the emitted event should contain data from the trigger observation. When the criterion is met, this observation value is passed to the event constructor (typically a closure or static constructor method) supplied to emit_with, and that constructor returns the concrete user-defined IxaEvent that subscribers will receive.

use ixa::{Context, define_entity, define_property, IxaEvent};
use ixa::entity::EntityId;
use ixa::triggers::{ContextTriggersExt, PropertyChangeTrigger, TriggerCriterion};

define_entity!(Person);
define_property!(struct Alive(bool), Person, default_const = Alive(true));

#[derive(IxaEvent)]
struct FirstDeath {
    person: EntityId<Person>,
}

let mut context = Context::new();

context.register_trigger(
    PropertyChangeTrigger::to(Alive(false))
        .once()
        .emit_with(|event| FirstDeath {
            person: event.entity_id,
        }),
);

context.subscribe_to_event(|_context, _event: FirstDeath| {
    // perform cleanup tasks
});

Structs

EntityCountTrigger

EntityCountTriggerEvent

PeriodicTimeTrigger

PeriodicTimeTriggerEvent

PropertyChangeTrigger

PropertyChangeTriggerEvent

PropertyValueCountTrigger

PropertyValueCountTriggerEvent

TimeTrigger

TimeTriggerEvent

TogglingTrigger

A complete installable trigger specification that emits activation and deactivation events when its paired criteria cause state changes.

TogglingTriggerCriteria

A pair of activation and deactivation criteria that can be bound to emitted events.

Trigger

A criterion bound to a user event constructor. Values of this type are not constructed directly but rather are returned by the emit_* methods on trigger criterion types. These values are “complete” triggers than can be “installed” on a context with context.register_trigger.

Enums

Direction

Direction in which a count changed to reach a threshold.

TriggerMode

Whether a trigger emits once or every time its criterion is satisfied.

Traits

ContextTriggersExt

Extension trait for registering triggers on a Context.

TriggerCriterion

A bare trigger criterion: the condition that can be monitored. This module provides a collection of types that implement this trait.

TriggerSpec

A complete installable trigger specification that can be passed to context.register_trigger. This is automatically implemented by the Trigger types returned by the emit_* methods on trigger criterion types. Client code should not implement this themselves.