moirai_core/executor/
control.rs

1//! Executor lifecycle control interface.
2
3/// Provides control operations for executor lifecycle management.
4///
5/// This trait enables external systems to manage executor state transitions,
6/// perform health checks, and coordinate shutdown procedures.
7#[allow(clippy::module_name_repetitions)]
8pub trait ExecutorControl: Send + Sync + 'static {
9    /// Block the current thread until the future completes.
10    ///
11    /// # Behavior Guarantees
12    /// - Blocks calling thread until future resolves
13    /// - Supports nested async operations within the future
14    /// - Handles panic propagation from the future
15    /// - May deadlock if future depends on blocked thread
16    ///
17    /// # Performance Characteristics
18    /// - Optimal for CPU-bound futures with minimal I/O
19    /// - May block calling thread indefinitely
20    /// - Memory: Future size + execution context
21    /// - Suitable for main thread or dedicated blocking contexts
22    fn block_on<F>(&self, future: F) -> F::Output
23    where
24        F: core::future::Future;
25
26    /// Attempt to run tasks without blocking.
27    ///
28    /// # Behavior Guarantees
29    /// - Non-blocking operation, returns immediately
30    /// - Returns true if any work was performed
31    /// - May perform multiple task executions in single call
32    /// - Suitable for integration with external event loops
33    ///
34    /// # Performance Characteristics
35    /// - O(1) operation, < 1μs typical latency
36    /// - Work stealing: Attempts to balance load across threads
37    /// - Suitable for event loops requiring non-blocking progress
38    fn try_run(&self) -> bool;
39
40    /// Shutdown the executor gracefully.
41    ///
42    /// # Behavior Guarantees
43    /// - Allows running tasks to complete naturally
44    /// - Prevents new tasks from being spawned
45    /// - Idempotent operation - safe to call multiple times
46    /// - Blocks until all worker threads have stopped
47    /// - Releases all resources and thread handles
48    ///
49    /// # Performance Characteristics
50    /// - Shutdown time: Depends on longest running task
51    /// - Resource cleanup: All memory and handles released
52    /// - Thread coordination: Uses efficient signaling
53    fn shutdown(&self);
54
55    /// Shutdown the executor with a timeout.
56    ///
57    /// # Behavior Guarantees
58    /// - Attempts graceful shutdown first
59    /// - Forces termination after timeout expires
60    /// - May result in task cancellation or abortion
61    /// - Guarantees executor stops within timeout + small overhead
62    ///
63    /// # Performance Characteristics
64    /// - Graceful phase: Same as `shutdown()`
65    /// - Forced phase: Immediate thread termination
66    /// - Timeout accuracy: ±10ms typical variance
67    fn shutdown_timeout(&self, timeout: core::time::Duration);
68
69    /// Check if the executor is shutting down.
70    ///
71    /// # Behavior Guarantees
72    /// - Returns true once shutdown has been initiated
73    /// - Eventually consistent across all threads
74    /// - Remains true until executor is fully stopped
75    ///
76    /// # Performance Characteristics
77    /// - O(1) operation, < 10ns latency
78    /// - Non-blocking atomic read operation
79    /// - Memory ordering: Acquire semantics
80    fn is_shutting_down(&self) -> bool;
81
82    /// Get the number of worker threads.
83    ///
84    /// # Behavior Guarantees
85    /// - Returns configured number of worker threads
86    /// - Does not include async or blocking thread pools
87    /// - Constant value set during executor creation
88    ///
89    /// # Performance Characteristics
90    /// - O(1) operation, immediate return
91    /// - No synchronization overhead
92    fn worker_count(&self) -> usize;
93
94    /// Get the current load (number of pending tasks).
95    ///
96    /// # Behavior Guarantees
97    /// - Returns approximate pending task count
98    /// - Eventually consistent across distributed queues
99    /// - May include tasks currently being executed
100    /// - Does not include blocked or suspended tasks
101    ///
102    /// # Performance Characteristics
103    /// - O(1) operation for local queues
104    /// - May involve atomic reads across threads
105    /// - Latency: < 100ns typical
106    fn load(&self) -> usize;
107}
moirai_core/executor/control.rs

moirai_core/executor/
control.rs
