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 // custom callback-failure handling
EventLoopOptions // copied capacity and default-error configuration
EventLoopErrorPolicy // default callback-failure policy
EventQueueOverflowAction // queue-capacity policy
EventQueueFullError // full-queue application failure

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

Callback Binding Patterns

bindEvent([Ep, ]callback) -> callable // bind a callback
bindEvent([Ep, ]sharedRecipient, method) -> callable // bind a recipient method
bindWeakEvent([Ep, ]weakRecipient, method) -> callable // bind a weak recipient method

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, ][options]) -> 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.queuedEventCount() -> std::size_t // snapshot excluding executing, delayed, and quit-control work
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([options]) -> ManagedEventThreadPtr // create an application-owned event thread
T::create([options]) -> 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) -> bool // report whether backend work was accepted
o.wakeFromBackend() // notify the owning loop of backend state

Event Loop Options Patterns

o.maximumQueuedEvents()/setMaximumQueuedEvents(count) // zero means unlimited ordinary waiting events
o.queueOverflowAction()/setQueueOverflowAction(action) // Terminate, FailApplication, Quit, Block, Ignore
o.errorPolicy()/setErrorPolicy(policy) // Ignore, Store, Quit, FailApplication