maiko/
supervisor_config.rs

1/// Runtime configuration for the supervisor and actors.
2///
3/// Controls channel buffer sizes and event batching behavior. Use the builder
4/// pattern to customize, or use [`Default`] for sensible defaults.
5///
6/// # Examples
7///
8/// ```rust
9/// use maiko::SupervisorConfig;
10///
11/// let config = SupervisorConfig::default()
12///     .with_broker_channel_capacity(512)          // Larger broker buffer
13///     .with_default_actor_channel_capacity(256)   // Larger actor mailboxes
14///     .with_default_max_events_per_tick(20);       // Process more events per cycle
15/// ```
16#[derive(Debug, Clone, PartialEq, Eq, Hash)]
17#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
18pub struct SupervisorConfig {
19    /// Size of the broker's input channel buffer.
20    /// Determines how many events can be queued before producers block (stage 1).
21    /// Default: 256
22    broker_channel_capacity: usize,
23
24    /// Default mailbox channel capacity for newly registered actors.
25    /// Individual actors can override this via [`ActorBuilder::channel_capacity`](crate::ActorBuilder::channel_capacity).
26    /// Default: 128
27    default_actor_channel_capacity: usize,
28
29    /// Maximum number of events an actor will process in a single tick cycle
30    /// before yielding control back to the scheduler.
31    /// Lower values improve fairness, higher values improve throughput.
32    /// Default: 10
33    default_max_events_per_tick: usize,
34
35    /// Buffer size for the monitoring event channel.
36    /// Default: 1024
37    monitoring_channel_capacity: usize,
38}
39
40impl Default for SupervisorConfig {
41    fn default() -> Self {
42        SupervisorConfig {
43            broker_channel_capacity: 256,
44            default_actor_channel_capacity: 128,
45            default_max_events_per_tick: 10,
46            monitoring_channel_capacity: 1024,
47        }
48    }
49}
50
51impl SupervisorConfig {
52    /// Set the per-actor channel capacity for stage 1 (actor to broker).
53    #[must_use]
54    pub fn with_broker_channel_capacity(mut self, capacity: usize) -> Self {
55        self.broker_channel_capacity = capacity;
56        self
57    }
58
59    /// Returns the per-actor channel capacity for stage 1 (actor to broker).
60    pub fn broker_channel_capacity(&self) -> usize {
61        self.broker_channel_capacity
62    }
63
64    /// Set the default maximum events processed per tick cycle for new actors.
65    ///
66    /// This controls batching behavior in the actor event loop.
67    /// After processing this many events, the actor yields to allow
68    /// other tasks to run and to call [`Actor::step`].
69    ///
70    /// Trade-offs:
71    /// - Lower values (1-5): Better fairness, more responsive `step()`, higher overhead
72    /// - Higher values (50-100): Better throughput, potential starvation of `step()`
73    ///
74    /// [`Actor::step`]: crate::Actor::step
75    #[must_use]
76    pub fn with_default_max_events_per_tick(mut self, limit: usize) -> Self {
77        self.default_max_events_per_tick = limit;
78        self
79    }
80
81    /// Returns the default maximum events processed per tick.
82    pub fn default_max_events_per_tick(&self) -> usize {
83        self.default_max_events_per_tick
84    }
85
86    /// Set the buffer size for the monitoring event channel.
87    #[must_use]
88    pub fn with_monitoring_channel_capacity(mut self, capacity: usize) -> Self {
89        self.monitoring_channel_capacity = capacity;
90        self
91    }
92
93    /// Returns the monitoring event channel capacity.
94    pub fn monitoring_channel_capacity(&self) -> usize {
95        self.monitoring_channel_capacity
96    }
97
98    /// Set the default mailbox channel capacity for new actors (stage 2).
99    #[must_use]
100    pub fn with_default_actor_channel_capacity(mut self, capacity: usize) -> Self {
101        self.default_actor_channel_capacity = capacity;
102        self
103    }
104
105    /// Returns the default mailbox channel capacity for new actors.
106    pub fn default_actor_channel_capacity(&self) -> usize {
107        self.default_actor_channel_capacity
108    }
109}
maiko/supervisor_config.rs

maiko/
supervisor_config.rs
