Event System Overview
The event system connects callbacks, timers, and background work through event loops. These topics explain the programming model, help you choose where loops run, and show how to connect callbacks safely. They then develop scheduling and the state needed to coordinate a complete task. For work spanning several loops, continue with communication, shutdown, and load control. Failure handling supports both paths; direct loop ownership and extension APIs form separate paths.
Event System Concepts and Facilities
Events in Erbsland Core introduces event loops and callbacks from the perspective of procedural C++ code. It explains how targets, invocations, timers, and event sources fit together, and when a main loop, worker thread, or application part is useful.
Application Event Loops
Running an Application with Event Loops builds a file monitor around the application’s main loop, then shows how a derived application can run setup and cleanup around that loop. It also explains when worker threads or application parts are useful next steps.
Processing Work on Event Threads
Processing Work on Event Threads explains thread creation, posting work, result ownership, and synchronization through thread joining. A file-hashing batch illustrates how exclusive access and value transfer avoid shared mutable result state.
Event Loops in Application Parts
Using Event Loops in Application Parts explains the execution and lifecycle model of a part’s dedicated loop. It uses a file server to demonstrate source ownership, readiness, cross-thread service calls, and asynchronous shutdown.
Connecting to Event Sources
Connecting to Event Sources follows a source from setup to result and explains the shared conventions behind targets, source-owned editors, replaceable handlers, and independent observers. It also shows how to send setup to the owner loop and access its network service.
Callback Ownership and Lifetime
Keeping Callbacks and Their Owners Alive explains what retains a source, timer, callback, and observer registration. You will see when value and strong captures are useful, how weak captures let recipients disappear, and why cancellation and callback completion are different lifetime questions.
Invocations and Timers
Scheduling Work and Timers shows how to defer a callback, choose a delayed invocation or retained timer, and cancel or replace a deadline. It compares repeating timer modes and develops a debounce for repeated input.
Simplifying Event Code with Bindings
Simplifying Event Code with Bindings turns nested result callbacks into reusable continuations bound to their receiving loop. Two checksum applications show the same operation with explicit invocation and event bindings. A pi calculator then separates required operation completion from an optional display.
Asynchronous Task Workflows
Building Workflows Across Callbacks uses the Checksum Packer to connect scanning and packing into one operation. It explains state transitions, result ownership, and success and failure paths coordinated by callbacks on the main loop.
Communication Between Loops
Communicating Between Event Loops routes requests to a worker and replies to a running main loop while keeping mutable state with its owner. It explains transferred values, recipient lifetime, obsolete replies, and completion paths that remain responsive.
Cancellation and Shutdown
Cancelling Work and Shutting Down follows resources through cancellation or close, final callbacks, loop termination, and thread joining. It distinguishes draining accepted callbacks from finishing asynchronous operations, and explains failure and deadline paths for shutdown.
Handling Event Failures
Handling Event Failures distinguishes synchronous exceptions, operation error notifications, and callback failures. It shows how to retrieve captured exceptions, choose a loop policy, and end a managed worker’s task without leaving its caller waiting for a missing result.
Keeping Loops Responsive Under Load
Keeping Event Loops Responsive Under Load starts with bounded outstanding requests and short callbacks, then develops queue capacity as a separate overload policy. It explains disposable updates, coalescing, blocking admission, and the limits of queue counts and timer deadlines.
Owning Loop Execution
The planned topic Driving Event Loops Directly covers dispatch controlled by a procedural host and standalone worker ownership. It forms an optional path for applications that need to drive execution themselves.
Extending the Event System
The extension tutorials are planned as a progression from a component’s public notifications to native integration. Designing Objects That Produce Events will start with an object that publishes events. Defining and Posting Typed Events will develop typed event data and routing, and Writing an Event Backend will connect custom work to the loop. Integrating Native Waiting and Custom Drivers will cover native waiting and custom drivers. These destinations are marked as planned topics until their tutorials are written.