agave_event_system/
lib.rs

1#![cfg_attr(docsrs, feature(doc_cfg))]
2//! An event system implemented on Linux.
3//!
4//! On all other targets, the public API is available but all operations are
5//! no-ops.
6//!
7//! [`EventSystem::stub()`] explicitly creates a no-op event system on any target.
8
9// This is needed to use the `#[event]` macro in order to resolve the [`Event`] trait.
10// The reason is that the macro expands to use [`agave_event_system::Event`],
11// but in the self crate it is referred to as [`crate::Event`].
12#[cfg(test)]
13extern crate self as agave_event_system;
14
15pub use {
16    crate::{
17        event_system::{
18            CreateEventSystemError, CreateStreamError, EventQueueError, EventSystem, StreamConfig,
19        },
20        publisher_factory::PublisherFactory,
21        queue_cell::{ByteArray, event_queue_cell_size},
22    },
23    agave_event_system_derive::event,
24};
25// wincode and wincode-dynamic are part of public API.
26pub use {wincode, wincode_dynamic};
27use {
28    wincode::{SchemaWrite, config::DefaultConfig},
29    wincode_dynamic::SchemaDynamic,
30};
31
32pub mod event_metadata;
33pub mod publisher;
34pub mod stream_name;
35pub mod stream_policy;
36pub mod subscriber;
37
38#[doc(hidden)]
39pub mod __private {
40    pub use crate::stream_name::macro_support::stream_name;
41
42    pub mod event_macro {
43        pub use {wincode::*, wincode_dynamic::*};
44    }
45}
46
47mod backend;
48#[cfg(target_os = "linux")] // cache_padded is only used by linux backend as of now
49pub(crate) mod cache_padded;
50mod event_system;
51mod publisher_factory;
52mod queue_cell;
53
54/// An event type that can be sent on an event stream.
55///
56/// The [`Event`] trait should only be implemented with the [`event`] macro.
57///
58/// ```
59/// # use agave_event_system::event;
60/// #[event]
61/// #[derive(Debug, PartialEq, Eq)]
62/// enum SlotEvents {
63///     Completed { slot: u64 },
64/// }
65/// ```
66///
67/// Events containing dynamically sized values must declare a
68/// `max_serialized_size` strictly greater than the statically known portion of
69/// their encoding.
70///
71/// ```
72/// # use agave_event_system::event;
73/// #[event(max_serialized_size = 1024)]
74/// struct Message {
75///     contents: String,
76/// }
77/// ```
78///
79/// Omitting the bound for a dynamically sized event is a compile-time error.
80///
81/// ```compile_fail
82/// # use agave_event_system::event;
83/// #[event]
84/// struct UnboundedMessage {
85///     contents: String,
86/// }
87/// ```
88///
89/// The bound must also exceed wincode's dynamic serialized-size lower bound.
90///
91/// ```compile_fail
92/// # use agave_event_system::event;
93/// #[event(max_serialized_size = 8)]
94/// struct UndersizedMessage {
95///     fixed: u64,
96///     contents: String,
97/// }
98/// ```
99pub trait Event: Sized + 'static + SchemaDynamic + SchemaWrite<DefaultConfig, Src = Self> {
100    /// The fixed-size storage used for an encoded event in a queue.
101    ///
102    /// This associated type works around the lack of stable generic const
103    /// expressions. The [`event`] macro defines it as a byte array sized from
104    /// [`SchemaDynamic::SERIALIZED_SIZE`].
105    type QueueCell: ByteArray;
106}
agave_event_system/lib.rs

agave_event_system/
lib.rs
