modo/runtime/task.rs
1use crate::error::Result;
2
3/// A service or resource that can be shut down gracefully.
4///
5/// Implement this trait for every long-running component that needs cleanup on
6/// process exit — HTTP servers, background workers, connection pools, etc.
7/// The [`run!`](crate::run) macro calls [`Task::shutdown`] on each registered
8/// task in declaration order after a shutdown signal is received.
9///
10/// # Contract
11///
12/// - Implementors must be `Send + 'static` so they can be moved across threads.
13/// - `shutdown` consumes `self` — the task cannot be used after shutdown.
14/// - Return `Err` only for genuinely unexpected failures; normal teardown should
15/// return `Ok(())`.
16pub trait Task: Send + 'static {
17 /// Shuts down this task and releases its resources.
18 ///
19 /// Called once by [`run!`](crate::run) after the process receives a
20 /// shutdown signal. The future must be `Send` because it may be awaited on
21 /// any Tokio thread.
22 ///
23 /// # Errors
24 ///
25 /// Returns [`modo::Error`](crate::Error) only when teardown encounters a
26 /// genuinely unexpected failure (for example, a worker panic surfaced via a
27 /// join handle). Normal, clean shutdown — including cases where a resource
28 /// is already closed — should return `Ok(())`. An error from one task does
29 /// not abort the remaining shutdown sequence in [`run!`](crate::run); it is
30 /// logged at `error` level and the next task is still invoked.
31 fn shutdown(self) -> impl std::future::Future<Output = Result<()>> + Send;
32}