Skip to content

Package: regimeflow::events

Summary

Event model for the engine and live runtime. Defines event types, queues, and dispatch infrastructure used by the event loop and live adapters.

Related diagrams: - Event Model - Order State Machine

File Index

File Purpose
regimeflow/events/dispatcher.h Event dispatch interface and helpers.
regimeflow/events/event.h Base event type and metadata.
regimeflow/events/event_queue.h Event queue implementation.
regimeflow/events/market_event.h Market data event types.
regimeflow/events/order_event.h Order lifecycle event types.
regimeflow/events/system_event.h System lifecycle and control events.

Type Index

Type Description
Event Base event interface (timestamp, source, type).
EventQueue Multi-producer queue with serialized consumer-side draining and priority ordering.
MarketEvent Tick/bar/order book events.
OrderEvent Submit, fill, cancel, reject events.
SystemEvent Start/stop/heartbeat and control events.

Lifecycle & Usage Notes

  • EventQueue is the backbone for EventLoop and must respect producer/consumer constraints.
  • Producers may enqueue concurrently, but draining and priority-queue rebuilds are serialized by the queue internals; do not add alternate drain paths that bypass that ownership model.
  • Dispatcher implementations should avoid blocking; long tasks should be delegated.

Type Details

Event

Base event interface with timestamp, event type, and origin metadata.

Fields and Helpers:

Member Description
timestamp Event time.
type Event category.
priority Scheduling priority (lower first).
sequence Monotonic sequence for tie-breaks.
symbol Associated symbol ID.
payload Variant payload for market/order/system data.
default_priority(type) Map event type to default priority.
make_market_event(bar/tick/quote/book) Build market event from data type.
make_system_event(kind, timestamp, code, id) Build system event.
make_order_event(kind, timestamp, order_id, ...) Build order event.

Method Details:

Type Hints:

  • type → EventType
  • kind → MarketEventKind / OrderEventKind / SystemEventKind
  • timestamp → Timestamp
  • event → Event
  • order_id → OrderId
  • fill_id → FillId
  • symbol → SymbolId

default_priority(type)

Parameters: type event type. Returns: Default priority. Throws: None.

make_market_event(bar/tick/quote/book)

Parameters: Market data object. Returns: Event. Throws: None.

make_system_event(kind, timestamp, code, id)

Parameters: kind system event kind; timestamp event time; code optional; id optional identifier. Returns: Event. Throws: None.

make_order_event(kind, timestamp, order_id, fill_id, quantity, price, symbol, commission)

Parameters: Event kind, time, identifiers, fill details. Returns: Event. Throws: None.

EventType / MarketEventKind / OrderEventKind / SystemEventKind

Event categories and subtypes.

MarketEventKind

Market event subtype enum.

OrderEventKind

Order event subtype enum.

SystemEventKind

System event subtype enum.

MarketEventPayload / OrderEventPayload / SystemEventPayload

Payload structures for event data.

OrderEventPayload

Order event payload fields.

SystemEventPayload

System event payload fields.

EventComparator

Priority comparator for deterministic event ordering.

MarketEvent

Represents ticks, bars, and order book updates. Feeds into strategies and indicators.

Alias:

Alias Description
MarketEvent Alias to MarketEventPayload.

OrderEvent

Represents order lifecycle transitions: submit, accept, fill, reject, cancel.

Alias:

Alias Description
OrderEvent Alias to OrderEventPayload.

SystemEvent

Control-plane events such as start, stop, heartbeat, and timer signals.

Alias:

Alias Description
SystemEvent Alias to SystemEventPayload.

EventQueue

Multi-producer event queue for Event objects. Producers append to a pending list and consumer-side operations drain into the priority queue under internal synchronization. This preserves deterministic priority ordering without racing producer appends.

Methods:

Method Description
push(event) Enqueue an event.
pop() Pop next event by priority.
peek() Peek next event without removing.
empty() Check if queue is empty.
size() Number of queued events.
clear() Clear all queued events.
~EventQueue() Destructor, clears and releases pool.

Method Details:

push(event)

Parameters: event to enqueue. Returns: void. Throws: None.

pop()

Parameters: None. Returns: Optional Event. Throws: None.

peek()

Parameters: None. Returns: Optional Event. Throws: None.

empty()

Parameters: None. Returns: bool. Throws: None.

size()

Parameters: None. Returns: size_t. Throws: None.

clear()

Parameters: None. Returns: void. Throws: None.

Dispatcher

Dispatches Event objects to interested handlers.

Methods:

Method Description
set_market_handler(handler) Set handler for market events.
set_order_handler(handler) Set handler for order events.
set_system_handler(handler) Set handler for system events.
set_user_handler(handler) Set handler for user events.
dispatch(event) Dispatch to appropriate handler.

Method Details:

set_market_handler(handler)

Parameters: handler callback. Returns: void. Throws: None.

set_order_handler(handler)

Parameters: handler callback. Returns: void. Throws: None.

set_system_handler(handler)

Parameters: handler callback. Returns: void. Throws: None.

set_user_handler(handler)

Parameters: handler callback. Returns: void. Throws: None.

dispatch(event)

Parameters: event to dispatch. Returns: void. Throws: None.

EventDispatcher

Alias for the dispatcher used by the engine.

Usage Examples

#include "regimeflow/events/event_queue.h"
#include "regimeflow/events/event.h"

regimeflow::events::EventQueue queue;
queue.push(regimeflow::events::make_system_event(
    regimeflow::events::SystemEventKind::DayStart,
    regimeflow::Timestamp::now()));
auto next = queue.pop();

See Also