arti/crates/tor-events/README.md

# tor-events

Tools for generating a stream of structured events, similar to C tor's `ControlPort`.

License: MIT OR Apache-2.0
Initial cut at a typed event framework for arti (arti#230). This implements a basic typed event broadcast mechanism, as described in arti#230: consumers of the new `tor-events` crate can emit `TorEvent` events, which others can consume via the `TorEventReceiver`. Under the hood, the crate uses the `async-broadcast` (https://github.com/smol-rs/async-broadcast) crate, and a `futures::mpsc::UnboundedSender` for the event emitters; these are glued together in the `EventReactor`, which must be run in a background thread for things to work. (This is done so event sending is always cheap and non-blocking, since `async-broadcast` senders don't have this functionality.) Additionally, the `TorEventKind` type is used to implement selective event reception / emission: receivers can subscribe to certain event types (and in fact start out receiving nothing), which filters the set of events they receive. Having no subscribers for a given event type means it won't even be emitted in the first place, making things more efficient. 2021-11-16 15:21:47 +00:00			`# tor-events`

run ./maint/readmes.sh 2021-11-29 11:29:28 +00:00			Tools for generating a stream of structured events, similar to C tor's `ControlPort`.
Initial cut at a typed event framework for arti (arti#230). This implements a basic typed event broadcast mechanism, as described in arti#230: consumers of the new `tor-events` crate can emit `TorEvent` events, which others can consume via the `TorEventReceiver`. Under the hood, the crate uses the `async-broadcast` (https://github.com/smol-rs/async-broadcast) crate, and a `futures::mpsc::UnboundedSender` for the event emitters; these are glued together in the `EventReactor`, which must be run in a background thread for things to work. (This is done so event sending is always cheap and non-blocking, since `async-broadcast` senders don't have this functionality.) Additionally, the `TorEventKind` type is used to implement selective event reception / emission: receivers can subscribe to certain event types (and in fact start out receiving nothing), which filters the set of events they receive. Having no subscribers for a given event type means it won't even be emitted in the first place, making things more efficient. 2021-11-16 15:21:47 +00:00
			`License: MIT OR Apache-2.0`