6 DR 20230809_1

Capture Events

Keywords: architecture, design

Participants: Manuel Hatzl

Event Flow

Default Flow:

1. An intermediary event is set at any point during program execution, containing the event-ID and message
2. The intermediary event-entry gets a unique UUID, because an event-ID may be set multiple times, but each entry is unique
3. Optional: Additional content may be added to the intermediary event-entry
4. Once the intermediary event is finalized by going out of scope, or manually using finalize(), it is converted to an event, and sent to the event handler using std::sync::mpsc::sync_channel
5. The event handler receives the event, and forwards the event to all subscribers listening to the event, again using std::sync::mpsc::sync_channel, but now one channel per subscriber
6. Every subscriber receives the event, and may react to it

Capturing Stopped:

1. An intermediary event is set at any point during program execution, containing the event-ID and message
2. The intermediary event-entry gets a unique UUID, because an event-ID may be set multiple times, but each entry is unique
3. Optional: Additional content may be added to the intermediary event-entry
4. Once the intermediary event is finalized by going out of scope, or manually using finalize(), it is converted to an event
5. If capturing is stopped, the event is not sent, but available in the thread the event was manually finalized

Global Filter:

Same steps as above, with the addition that the event is only sent to the event handler if the filter allows it.

Why mpsc::sync_channel?

With sync_channel, it is possible to send events without blocking the sending thread on every send(), because a send-buffer can be set per channel.

Why the indirection with the event handler?

The std library only offers multiple producer single consumer channels for now, but there might be multiple subscribers (consumers) listening for events.

Other crates offering multiple consumer channels, forwarded events to the first consumer that receives the event. This is also not acceptable, because every subscriber must receive the event.

While the indirection might be a bottleneck, the approach makes it possible to stick with std, which reduces the number of dependencies.

Event Handler

The event handler is moved in its own thread, continuously blocking until the next event is received.

while let Ok(event) = handler.recv() {
    // forward event to subscriber
}

Caveat: Because recv() blocks the thread until an event is received, the event handler only reacts to events.