overlord_event_system

Trait EventHandler

pub trait EventHandler<E, S>
where
    E: Event,
    S: State,
{
    type Context: EventHandlerContext;

    // Required methods
    fn create_context_for_batch(
        &self,
        state: &S,
    ) -> impl Future<Output = Result<Self::Context, Error>> + Send;
    fn handle_event(
        &mut self,
        ctx: &Self::Context,
        event: &E,
        meta: EventMeta,
        prev_state: &S,
        state: S,
    ) -> impl Future<Output = Result<EventHandleResult<E, S>, Error>> + Send;
    fn compute_fields(&self, state: &mut S, prev_state: &S) -> Vec<E>;
    fn collect_due_scheduled(&mut self, current_tick: u64) -> Vec<E>;
    fn finalize_state(
        &self,
        ctx: &Self::Context,
        state: &mut S,
    ) -> impl Future<Output = Result<(), Error>> + Send;
    fn persist_in_memory_state(
        &self,
        ctx: &Self::Context,
        state: &S,
    ) -> impl Future<Output = Result<(), Error>> + Send;

    // Provided methods
    fn event_needs_full_context(&self, _event: &E, _state: &S) -> bool { ... }
    fn create_pure_context_for_batch(
        &self,
        state: &S,
    ) -> impl Future<Output = Result<Self::Context, Error>> + Send { ... }
    fn context_is_pure(&self, _ctx: &Self::Context) -> bool { ... }
    fn upgrade_context(
        &self,
        ctx: Self::Context,
        _state: &S,
    ) -> impl Future<Output = Result<Self::Context, Error>> + Send
       where Self::Context: Send { ... }
}

Required Associated Types§

type Context: EventHandlerContext

Required Methods§

fn create_context_for_batch( &self, state: &S, ) -> impl Future<Output = Result<Self::Context, Error>> + Send

fn handle_event( &mut self, ctx: &Self::Context, event: &E, meta: EventMeta, prev_state: &S, state: S, ) -> impl Future<Output = Result<EventHandleResult<E, S>, Error>> + Send

One call per event. prev_state is the System’s state before this event (same data as state, by reference — avoids an extra clone for the compute_fields diff). Impls are responsible for: pure state mutation -> compute_fields fold (diff vs prev_state, runs for failed results too; prepend emitted events) -> DB persistence / validation -> analytics deferral. Err(_) aborts the whole batch (txn rollback). “Soft” failures must be returned as Ok(EventHandleResult::fail(...)).

fn compute_fields(&self, state: &mut S, prev_state: &S) -> Vec<E>

Can be used to compute fields that arent stored in database, but computed from stored data. Also can emit events on some logical data changes. This events eventually can change state. Sync, no DB. Called by impls inside handle_event and by System::apply_state_with_compute_fields.

fn collect_due_scheduled(&mut self, current_tick: u64) -> Vec<E>

Events the handler scheduled internally that are due at current_tick. Drained alongside the delayed/cron plugins on every tick. Lets a handler own domain scheduling (e.g. the fight clock) so the same state drives both the live system and standalone simulations. Deliberately has no default body — every impl must state it explicitly.

fn finalize_state( &self, ctx: &Self::Context, state: &mut S, ) -> impl Future<Output = Result<(), Error>> + Send

fn persist_in_memory_state( &self, ctx: &Self::Context, state: &S, ) -> impl Future<Output = Result<(), Error>> + Send

Persist in-memory state to DB context before commit. Called by flush_state to save changes accumulated between batches.

Provided Methods§

fn event_needs_full_context(&self, _event: &E, _state: &S) -> bool

Whether handling event may touch the context’s backing resources (DB transaction, persistence). Handlers that support pure (DB-less) contexts override this for events whose handling is pure logic end-to-end; the default — true for every event — keeps the eager full-context behavior. state is the System state at dispatch time — handlers use it for state-dependent persistence (e.g. quest subscriptions that persist progress on otherwise-pure events).

fn create_pure_context_for_batch( &self, state: &S, ) -> impl Future<Output = Result<Self::Context, Error>> + Send

Create a context for a batch whose events all have event_needs_full_context == false. Defaults to the full context.

fn context_is_pure(&self, _ctx: &Self::Context) -> bool

Whether ctx is a pure (DB-less) context that must be upgraded via upgrade_context before handling a full-context event.

fn upgrade_context( &self, ctx: Self::Context, _state: &S, ) -> impl Future<Output = Result<Self::Context, Error>> + Send
where Self::Context: Send,

Upgrade a pure context into a full one, carrying over all state accumulated so far. Only called when context_is_pure is true.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors§