Event Domain API Guidelines

Core Semantics

owner loop = one loop that serializes a source's state and callbacks

Primary Types

Event // one typed event with optional data and posting time
Events // target for posting events, invoking callbacks, and accessing backends
EventLoop // serialized event dispatch and native wait loop
EventTimer // thread-safe retained scheduled-callback handle
EventThread // event loop running on a dedicated thread

Event Value Types

EventId, EventBackendId // registered event and backend identifiers
EventData // base for typed event payloads
EventSource, EventEditor // event-loop-owned source and source-owned handler editor
EventSubscription // move-only lifetime handle for one observer registration
EventIdInfo, EventBackendIdInfo // registered identifier metadata
EventCallback // callback executed by an event loop
EventRegistry // application-managed identifier registry

Scheduling and Thread Types

EventScheduler // scheduling frontend supplied by the scheduler backend
EventTimerMode // inactive, once, fixed-delay, or fixed-rate scheduling mode
ManagedEventThread // application-owned event thread
UnmanagedEventThread // standalone event thread
EventLoopErrorAction, EventLoopErrorHandler // callback-failure handling policy

Backend Types

EventBackend // native or domain event backend interface
EventBackendTarget // backend-facing loop target for posting and waking
EventLoopDriver // injectable native wait and wake abstraction

Pattern Definitions

Ep = EventsPtr/EventLoopPtr // event target or concrete loop pointer

Event Value Patterns

T(identifier[, data]) // create an event with its posting time
o.identifier()/time()/data() -> T // inspect event identity, time, or payload
T::register❮Kind❯(name) -> T // register a stable event or backend identifier
o.info(identifier) -> T // inspect registered identifier metadata

Dispatch Patterns

o.post(event) // enqueue a raw event
o.invoke(callback) // enqueue callback execution in the target loop
o.invokeAfter(delay, callback) // enqueue a fire-and-forget delayed callback
o.get❮Backend❯() -> T& // access one backend frontend interface
currentEvents() -> EventsPtr // access the loop currently running on this thread

Subscription Patterns

o.events() -> TEventEditor& // access a source-owned editor on the owner loop
o.on❮Event❯(callback) -> T& // replace the one source-owned handler; do not combine with an add form
o.add❮Event❯(callback) -> EventSubscription // add an observer; do not combine with an on form
o.source() -> EventSourcePtr // retain the source that owns an editor
o.target() -> EventsPtr // retain the target that dispatches the callbacks
o.ownerEvents() -> EventsPtr // access the loop that owns an event source

Event Loop Patterns

T::create([driver-or-backend]) -> EventLoopPtr // create a loop with optional integration
o.run() // run until stopped or quit
o.runOnce([maximumWait]) -> bool // perform one bounded event-loop cycle
o.runUntilIdle() -> std::size_t // dispatch all immediately available work
o.stop()/quit() // request immediate stop or queued graceful termination
o.isRunning()/isQuitRequested() -> bool // inspect loop lifecycle state
o.hasError() -> bool // test whether a callback failure is queued
o.takeError() -> std::exception_ptr // consume the oldest callback failure
o.setErrorHandler(handler) // configure callback-failure handling
o.registerBackend(backend) // attach a backend before the loop runs

Timer and Thread Patterns

o.createTimer(callback) -> EventTimerPtr // create an inactive retained timer
o.startOnce/startFixedDelay/startFixedRate(interval) // schedule retained work
o.stop() // cancel scheduled timer work
o.isActive() -> bool // test whether a timer is scheduled or pending
o.mode()/interval() -> T // inspect timer scheduling
o.createEventThread() -> ManagedEventThreadPtr // create an application-owned event thread
T::create() -> UnmanagedEventThreadPtr // create a standalone event thread
o.start() // start a one-shot event thread; never restart a joined thread
o.quit() // idempotently request graceful termination without waiting
o.join() // wait without requesting termination; never call from the worker itself
o.eventLoop()/events() -> Ep // access a thread's loop or event target

Backend Patterns

o.attach(target, driver) // attach the backend to one event loop
o.poll(now)/handleEvent(event) -> bool // collect or handle backend work
o.nextWakeTime() -> time::TimePoint // report the next requested poll time
o.wait([maximumWait])/wake() // wait for or signal native activity
o.postFromBackend(event)/wakeFromBackend() // notify the owning loop from a backend