1use crate::{ServiceHandle, ShutdownError};
2use async_trait::async_trait;
3use std::{
4 future::Future,
5 sync::{
6 Arc,
7 atomic::{AtomicU8, Ordering},
8 },
9};
10use tokio::{
11 sync::watch,
12 task::{JoinError, JoinHandle},
13};
14
15const RUNNING: u8 = 0;
16const SHUTTING_DOWN: u8 = 1;
17const EXITED: u8 = 2;
18
19#[derive(Clone, Copy, Debug, PartialEq, Eq)]
20pub enum BackgroundTaskExitKind {
21 Completed,
22 Failed,
23 Panicked,
24}
25
26#[derive(Clone, Debug, PartialEq, Eq)]
27pub struct BackgroundTaskExit {
28 pub service: &'static str,
29 pub kind: BackgroundTaskExitKind,
30 pub message: Option<String>,
31}
32
33pub trait BackgroundTaskObserver: Send + Sync {
34 fn exited(&self, event: &BackgroundTaskExit);
35}
36
37pub struct SupervisedTaskHandle {
38 service: &'static str,
39 shutdown: watch::Sender<bool>,
40 task: JoinHandle<Result<(), ShutdownError>>,
41 state: Arc<AtomicU8>,
42}
43
44impl SupervisedTaskHandle {
45 #[must_use]
46 pub fn spawn<F, Fut, O>(service: &'static str, observer: O, run: F) -> Self
47 where
48 F: FnOnce(watch::Receiver<bool>) -> Fut + Send + 'static,
49 Fut: Future<Output = Result<(), ShutdownError>> + Send + 'static,
50 O: BackgroundTaskObserver + 'static,
51 {
52 let (shutdown, receiver) = watch::channel(false);
53 let state = Arc::new(AtomicU8::new(RUNNING));
54 let task_state = Arc::clone(&state);
55 let task = tokio::spawn(async move {
56 let outcome = task_outcome(tokio::spawn(run(receiver)).await);
57 if task_state
58 .compare_exchange(RUNNING, EXITED, Ordering::AcqRel, Ordering::Acquire)
59 .is_ok()
60 {
61 let event = BackgroundTaskExit {
62 service,
63 kind: outcome.kind,
64 message: outcome.message,
65 };
66 let _ = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
67 observer.exited(&event);
68 }));
69 }
70 outcome.result
71 });
72 Self {
73 service,
74 shutdown,
75 task,
76 state,
77 }
78 }
79
80 pub async fn shutdown(self) -> Result<(), ShutdownError> {
86 let Self {
87 shutdown,
88 task,
89 state,
90 ..
91 } = self;
92 let _ = state.compare_exchange(RUNNING, SHUTTING_DOWN, Ordering::AcqRel, Ordering::Acquire);
93 let _ = shutdown.send(true);
94 task.await.map_err(ShutdownError::new)?
95 }
96}
97
98#[async_trait]
99impl ServiceHandle for SupervisedTaskHandle {
100 fn service(&self) -> &'static str {
101 self.service
102 }
103
104 async fn shutdown(self: Box<Self>) -> Result<(), ShutdownError> {
105 SupervisedTaskHandle::shutdown(*self).await
106 }
107}
108
109struct TaskOutcome {
110 result: Result<(), ShutdownError>,
111 kind: BackgroundTaskExitKind,
112 message: Option<String>,
113}
114
115fn task_outcome(result: Result<Result<(), ShutdownError>, JoinError>) -> TaskOutcome {
116 match result {
117 Ok(Ok(())) => TaskOutcome {
118 result: Ok(()),
119 kind: BackgroundTaskExitKind::Completed,
120 message: None,
121 },
122 Ok(Err(error)) => {
123 let message = error.to_string();
124 TaskOutcome {
125 result: Err(error),
126 kind: BackgroundTaskExitKind::Failed,
127 message: Some(message),
128 }
129 }
130 Err(error) => {
131 let kind = if error.is_panic() {
132 BackgroundTaskExitKind::Panicked
133 } else {
134 BackgroundTaskExitKind::Failed
135 };
136 let message = error.to_string();
137 TaskOutcome {
138 result: Err(ShutdownError::new(&message)),
139 kind,
140 message: Some(message),
141 }
142 }
143 }
144}
145
146#[cfg(test)]
147mod tests {
148 use super::{
149 BackgroundTaskExit, BackgroundTaskExitKind, BackgroundTaskObserver, SupervisedTaskHandle,
150 };
151 use crate::{ServiceHandle, ShutdownError};
152 use std::sync::{
153 Arc, Mutex,
154 atomic::{AtomicBool, Ordering},
155 };
156
157 #[derive(Clone, Default)]
158 struct RecordingObserver(Arc<Mutex<Vec<BackgroundTaskExit>>>);
159
160 impl BackgroundTaskObserver for RecordingObserver {
161 fn exited(&self, event: &BackgroundTaskExit) {
162 self.0.lock().unwrap().push(event.clone());
163 }
164 }
165
166 impl RecordingObserver {
167 async fn wait_for_exit(&self) -> BackgroundTaskExit {
168 tokio::time::timeout(std::time::Duration::from_secs(1), async {
169 loop {
170 if let Some(event) = self.0.lock().unwrap().first().cloned() {
171 return event;
172 }
173 tokio::task::yield_now().await;
174 }
175 })
176 .await
177 .unwrap()
178 }
179 }
180
181 #[tokio::test]
182 async fn observes_unexpected_completion() {
183 let observer = RecordingObserver::default();
184 let handle =
185 SupervisedTaskHandle::spawn("completed", observer.clone(), |_| async { Ok(()) });
186 let event = observer.wait_for_exit().await;
187 assert_eq!(event.kind, BackgroundTaskExitKind::Completed);
188 assert_eq!(event.service, "completed");
189 assert!(event.message.is_none());
190 handle.shutdown().await.unwrap();
191 }
192
193 #[tokio::test]
194 async fn observes_task_errors_and_returns_them_from_shutdown() {
195 let observer = RecordingObserver::default();
196 let handle = SupervisedTaskHandle::spawn("failed", observer.clone(), |_| async {
197 Err(ShutdownError::new("injected task error"))
198 });
199 let event = observer.wait_for_exit().await;
200 assert_eq!(event.kind, BackgroundTaskExitKind::Failed);
201 assert_eq!(event.message.as_deref(), Some("injected task error"));
202 assert_eq!(
203 Box::new(handle).shutdown().await.unwrap_err().to_string(),
204 "injected task error"
205 );
206 }
207
208 #[tokio::test]
209 async fn observes_panics_and_returns_them_from_shutdown() {
210 let observer = RecordingObserver::default();
211 let handle = SupervisedTaskHandle::spawn("panicked", observer.clone(), |_| async {
212 panic!("injected task panic");
213 });
214 let event = observer.wait_for_exit().await;
215 assert_eq!(event.kind, BackgroundTaskExitKind::Panicked);
216 assert!(event.message.unwrap().contains("injected task panic"));
217 assert!(handle.shutdown().await.is_err());
218 }
219
220 #[tokio::test]
221 async fn expected_shutdown_is_not_observed_as_an_exit() {
222 let observer = RecordingObserver::default();
223 let handle =
224 SupervisedTaskHandle::spawn("stopped", observer.clone(), |mut shutdown| async move {
225 shutdown.changed().await.map_err(ShutdownError::new)?;
226 Ok(())
227 });
228 handle.shutdown().await.unwrap();
229 assert!(observer.0.lock().unwrap().is_empty());
230 }
231
232 #[tokio::test]
233 async fn observer_panics_do_not_change_the_task_result() {
234 struct PanickingObserver(Arc<AtomicBool>);
235 impl BackgroundTaskObserver for PanickingObserver {
236 fn exited(&self, _: &BackgroundTaskExit) {
237 self.0.store(true, Ordering::Release);
238 panic!("injected observer panic");
239 }
240 }
241
242 let observed = Arc::new(AtomicBool::new(false));
243 let handle = SupervisedTaskHandle::spawn(
244 "observed",
245 PanickingObserver(Arc::clone(&observed)),
246 |_| async { Ok(()) },
247 );
248 tokio::time::timeout(std::time::Duration::from_secs(1), async {
249 while !observed.load(Ordering::Acquire) {
250 tokio::task::yield_now().await;
251 }
252 })
253 .await
254 .unwrap();
255 handle.shutdown().await.unwrap();
256 }
257}