Skip to content

Redesign event management #28

Closed

Description

@detlefarend

Motivation

The current event management provides string-based event IDs and allows handlers to be registered for individual events. For higher-level adaptive applications, event generation should become configurable in a generic and reusable way.

A concrete use case is an adaptive model such as CellStream, which may expose both low-frequency state transitions (for example, creation/removal of clusters or saturation) and high-frequency events (for example, a cluster being fed or drained). These events should be configurable independently from the generic adaptation mechanism.

In particular, an event may either be disabled, emitted as an event only, or emitted and additionally count as a model adaptation.

Since events may occur in hot paths and potentially at instance frequency, event handling must also be lightweight. Routine logging inside the event manager is therefore undesirable, and event-object creation / dispatch should avoid unnecessary overhead.

Proposed design

mlpro.bf.events

Introduce a generic event configuration layer:

  • EventMode
    • OFF = 0
    • ON = 1
  • EventConfig
    • generic base class for implementation-specific event configurations
    • may define arbitrary event switches/parameters
  • EventManager
    • receives a generic p_events: EventConfig
    • keeps the existing string-based event-ID / handler-registration mechanism

The concrete EventConfig subclasses define which events an implementation exposes.

As a convention, the name of an event switch in an EventConfig subclass should be identical to the corresponding event ID. Example:

@dataclass
class MyEvents(EventConfig):

    model_changed: EventMode = EventMode.OFF

corresponds to event ID:

"model_changed"

This is deliberately a convention, not something enforced or inferred by MLPro. The concrete implementation is responsible for using matching event IDs.

mlpro.bf.ml

Introduce an ML-specific extension:

  • EventModeML
    • OFF = 0
    • ON = 1
    • ADAPTATION = 2

Semantics:

  • OFF: do not emit the event
  • ON: emit the event only
  • ADAPTATION: emit the event and additionally report a model adaptation

This allows individual events to participate in the generic adaptation mechanism without forcing every state transition to trigger an adaptation event.

The existing adaptation/event flow should be reviewed accordingly, especially the interaction between model-specific events, adapt() / _adapted(), the generic adapted event, and downstream adapt_on_event() handlers.

Performance / event dispatch

Event dispatch is a fundamental hot-path operation. High-frequency events must not cause avoidable framework overhead.

The following principles apply:

  • EventManager shall not inherit from Log merely for event-dispatch logging.
  • Routine messages such as "event fired", "calling handler", or "no handlers registered" shall not be emitted.
  • Classes that require logging shall inherit / compose logging explicitly instead of receiving it transitively through EventManager.
  • _raise_event() should use a minimal dispatch path: direct lookup of registered handlers, immediate return if no handler exists, and direct handler invocation.
  • Event-object creation should be tuned so that disabled or otherwise unused events do not cause unnecessary object creation or preparation work.
  • Event processing must remain efficient enough for events that may occur once per processed instance.

Event object redesign

Refactor Event into a lightweight, extensible dataclass.

Proposed base model:

@dataclass(kw_only=True)
class Event:
    p_raising_object: object
    p_tstamp: datetime = field(default_factory=datetime.now)

Design principles:

  • p_raising_object identifies the event source.
  • p_tstamp is optional and defaults to the creation time via default_factory=datetime.now.
  • kw_only=True keeps inheritance extensible and avoids argument-order conflicts when subclasses introduce additional mandatory payload fields.
  • Specialized event classes shall extend Event with explicit typed dataclass fields.
  • Arbitrary payload should not be modeled as a magic **p_kwargs field inside the dataclass. Where truly required, use an explicit mapping field such as p_kwargs: dict = field(default_factory=dict).
  • Event creation should stay cheap enough for hot-path usage.

Documentation

Because these classes form fundamental building blocks, both the generic event configuration and the ML-specific adaptation mode need clear documentation and examples.

Each concrete EventConfig subclass should document:

  • the available event switches,
  • the corresponding event IDs,
  • the exact event semantics / trigger condition,
  • the event payload,
  • and the supported event modes.

Todos

  • Refactor Event to @dataclass(kw_only=True)
    • Replace eager timestamp defaults with field(default_factory=datetime.now)
    • Review existing event constructor calls for compatibility
    • Review subclasses and migrate payload to explicit typed dataclass fields where practical
    • Decide whether a generic payload mapping is still required for backward compatibility
    • Add tests for default/custom timestamps, inheritance, and event payload handling
  • Remove logging dependency from EventManager and refactor affected MLPro classes accordingly
  • Tune _raise_event() for minimal handler lookup and dispatch overhead
  • Introduce EventMode in mlpro.bf.events with OFF and ON
  • Introduce generic base class EventConfig in mlpro.bf.events
  • Add p_events: EventConfig to EventManager
  • Define/document the convention EventConfig attribute name == event ID
  • Ensure that this convention remains implementation responsibility and is not enforced by MLPro
  • Introduce EventModeML in mlpro.bf.ml with OFF, ON, and ADAPTATION
  • Define the exact semantics of EventModeML.ADAPTATION
  • Review the interaction between model-specific events and adapt() / _adapted()
  • Review the generic adapted event and downstream adapt_on_event() handling
  • Ensure high-frequency model events can be emitted without necessarily triggering generic adaptation
  • Add API documentation for EventMode, EventConfig, and EventModeML
  • Add a minimal generic example for configurable event handling
  • Add an ML example showing the difference between ON and ADAPTATION
  • Update relevant tests for event configuration, handler registration, adaptation behavior, and high-frequency dispatch

Activity

  1. self-assigned this
    on Oct 1, 2026
  2. added a commit that references this issue on Oct 5, 2026
    95fc748
  3. linked a pull request that will close this issuev2.3.0: Enhancements, fixes #27on Oct 5, 2026
  4. added 4 commits that reference this issue on Oct 5, 2026
    4c75587
    63f9e86
    bacf7d0
    a6e4792
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions