astrs_node_api/runtime.rs
1//! [`NodeRuntime`] — the async runtime a node's session lives on.
2//!
3//! Blueprint §9.1 shows a node whose `main` is an ordinary synchronous
4//! function, and also promises `recv_async()`. Both have to work, from the
5//! same [`crate::Node`], without the author choosing a colour up front. This
6//! module is the one place that reconciles them.
7//!
8//! # Three situations, three behaviours
9//!
10//! | Where `Node::init…` is called | Runtime | Blocking calls |
11//! |---|---|---|
12//! | An ordinary `fn main` | A two-worker multi-thread runtime this node owns | Work |
13//! | Inside `#[tokio::main]` / a multi-thread runtime | The caller's | Work, through [`tokio::task::block_in_place`] |
14//! | Inside a current-thread runtime (`#[tokio::test]`) | The caller's | Refused with [`NodeError::BlockingInAsync`] |
15//!
16//! The third row is the interesting one. A current-thread runtime has exactly
17//! one thread; blocking it is not slow, it is a *deadlock* — the task that
18//! would deliver the awaited value can never run. Returning a typed error that
19//! names the `_async` twin to call instead is the only honest answer, and it
20//! turns a hang into a compile-cycle-length fix.
21//!
22//! # Examples
23//!
24//! ```
25//! use astrs_node_api::runtime::NodeRuntime;
26//!
27//! let runtime = NodeRuntime::acquire()?;
28//! assert!(runtime.is_owned(), "no runtime was running, so one was built");
29//! assert!(runtime.can_block());
30//! # Ok::<(), astrs_node_api::NodeError>(())
31//! ```
32
33use std::future::Future;
34use std::sync::Arc;
35
36use std::sync::OnceLock;
37
38use tokio::runtime::{Builder, Handle, RuntimeFlavor};
39use tokio::task::JoinHandle;
40
41/// Backs [`NodeRuntime::fallback_handle`]; see that function.
42static FALLBACK_HANDLE: OnceLock<Handle> = OnceLock::new();
43
44use crate::error::{NodeError, Result};
45
46/// The number of worker threads an owned node runtime starts with.
47///
48/// Two, not one: the session's reader and writer tasks are both long-lived
49/// and both spend their lives parked on I/O, and a single worker would make
50/// their wakeups serialise behind each other for no reason. Not more than
51/// two, because a node's own work belongs on the node's own threads — this
52/// runtime exists to move frames, not to be a thread pool.
53pub const OWNED_WORKER_THREADS: usize = 2;
54
55/// A tokio runtime owned by a node, shut down without blocking.
56///
57/// Dropping a `tokio::runtime::Runtime` **panics** when it happens inside an
58/// asynchronous context, because the drop blocks until the worker threads
59/// join. A node built outside a runtime and dropped inside one is an ordinary
60/// thing for a test or a `spawn_blocking` body to do, so this wrapper calls
61/// [`shutdown_background`](tokio::runtime::Runtime::shutdown_background)
62/// instead: the workers are detached and reaped by the process rather than
63/// joined by the dropping thread.
64#[derive(Debug)]
65pub struct OwnedRuntime(Option<tokio::runtime::Runtime>);
66
67impl OwnedRuntime {
68 /// The handle to spawn on.
69 ///
70 /// The `Option` is `Some` for the whole life of the value; it is emptied
71 /// only by [`Drop`], after which nothing can call this.
72 fn handle(&self) -> Option<&Handle> {
73 self.0.as_ref().map(tokio::runtime::Runtime::handle)
74 }
75
76 /// Runs `future` to completion on this runtime.
77 fn block_on<F: Future>(&self, future: F) -> Option<F::Output> {
78 self.0.as_ref().map(|runtime| runtime.block_on(future))
79 }
80}
81
82impl Drop for OwnedRuntime {
83 fn drop(&mut self) {
84 if let Some(runtime) = self.0.take() {
85 runtime.shutdown_background();
86 }
87 }
88}
89
90/// The runtime a node's background tasks run on.
91#[derive(Debug, Clone)]
92pub enum NodeRuntime {
93 /// A runtime this node built and owns; it shuts down when the last
94 /// handle drops.
95 Owned(Arc<OwnedRuntime>),
96 /// A runtime the caller already had running.
97 Borrowed(Handle),
98}
99
100impl NodeRuntime {
101 /// The runtime to use here: the caller's if one is running, otherwise a
102 /// freshly built one.
103 ///
104 /// # Errors
105 ///
106 /// [`NodeError::Runtime`] when no runtime is running and one cannot be
107 /// built (which in practice means the process cannot start threads).
108 pub fn acquire() -> Result<Self> {
109 match Handle::try_current() {
110 Ok(handle) => Ok(Self::Borrowed(handle)),
111 Err(_) => Self::owned(),
112 }
113 }
114
115 /// A freshly built runtime, ignoring any the caller has.
116 ///
117 /// # Errors
118 ///
119 /// [`NodeError::Runtime`] when the runtime cannot be built.
120 pub fn owned() -> Result<Self> {
121 let runtime = Builder::new_multi_thread()
122 .worker_threads(OWNED_WORKER_THREADS)
123 .thread_name("astrs-node")
124 .enable_all()
125 .build()
126 .map_err(|error| NodeError::Runtime(error.to_string()))?;
127 Ok(Self::Owned(Arc::new(OwnedRuntime(Some(runtime)))))
128 }
129
130 /// Whether this node built its own runtime.
131 #[must_use]
132 pub const fn is_owned(&self) -> bool {
133 matches!(self, Self::Owned(_))
134 }
135
136 /// The tokio handle to spawn on.
137 #[must_use]
138 pub fn handle(&self) -> &Handle {
139 match self {
140 // The inner `Option` is emptied only by `OwnedRuntime::drop`, at
141 // which point no `&self` can exist; the fallback keeps this total
142 // without an unwrap.
143 Self::Owned(runtime) => runtime.handle().unwrap_or_else(|| self.fallback_handle()),
144 Self::Borrowed(handle) => handle,
145 }
146 }
147
148 /// The handle used if an owned runtime were ever observed after its drop
149 /// — unreachable, and never taken in practice.
150 fn fallback_handle(&self) -> &Handle {
151 match self {
152 Self::Borrowed(handle) => handle,
153 Self::Owned(_) => FALLBACK_HANDLE.get_or_init(|| {
154 Builder::new_current_thread()
155 .build()
156 .map_or_else(|_| Handle::current(), |runtime| runtime.handle().clone())
157 }),
158 }
159 }
160
161 /// Spawns a background task.
162 pub fn spawn<F>(&self, future: F) -> JoinHandle<F::Output>
163 where
164 F: Future + Send + 'static,
165 F::Output: Send + 'static,
166 {
167 self.handle().spawn(future)
168 }
169
170 /// Whether a blocking call from *this* thread is safe.
171 ///
172 /// False exactly in the deadlock case: the calling thread is the single
173 /// worker of a current-thread runtime.
174 #[must_use]
175 pub fn can_block(&self) -> bool {
176 match Handle::try_current() {
177 Ok(handle) => handle.runtime_flavor() != RuntimeFlavor::CurrentThread,
178 Err(_) => true,
179 }
180 }
181
182 /// Runs `future` to completion, blocking the calling thread.
183 ///
184 /// # Errors
185 ///
186 /// [`NodeError::BlockingInAsync`] when the calling thread is a
187 /// current-thread runtime's only worker; `method` and `alternative` name
188 /// what was called and what to call instead.
189 pub fn block_on<F: Future>(
190 &self,
191 method: &'static str,
192 alternative: &'static str,
193 future: F,
194 ) -> Result<F::Output> {
195 match Handle::try_current() {
196 Ok(handle) => match handle.runtime_flavor() {
197 RuntimeFlavor::CurrentThread => Err(NodeError::BlockingInAsync {
198 method,
199 alternative,
200 }),
201 // `block_in_place` moves the current task off its worker so
202 // the runtime keeps making progress while this thread blocks.
203 _ => Ok(tokio::task::block_in_place(|| handle.block_on(future))),
204 },
205 Err(_) => match self {
206 Self::Owned(runtime) => runtime
207 .block_on(future)
208 .ok_or_else(|| NodeError::Runtime("the node runtime is gone".to_owned())),
209 // A borrowed handle whose runtime is not *this* thread's:
210 // blocking here cannot deadlock that runtime, and
211 // `Handle::block_on` is the documented way to do it.
212 Self::Borrowed(handle) => Ok(handle.block_on(future)),
213 },
214 }
215 }
216}
217
218#[cfg(test)]
219mod tests {
220 #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
221
222 use super::*;
223
224 #[test]
225 fn outside_a_runtime_one_is_built_and_blocking_works() {
226 let runtime = NodeRuntime::acquire().unwrap();
227 assert!(runtime.is_owned());
228 assert!(runtime.can_block());
229 let value = runtime
230 .block_on("test", "test_async", async { 7_u32 })
231 .unwrap();
232 assert_eq!(value, 7);
233 }
234
235 #[test]
236 fn an_owned_runtime_drives_spawned_tasks_without_a_block_on() {
237 let runtime = NodeRuntime::owned().unwrap();
238 let (tx, rx) = std::sync::mpsc::channel();
239 let _task = runtime.spawn(async move {
240 let _ = tx.send(11_u32);
241 });
242 assert_eq!(
243 rx.recv_timeout(std::time::Duration::from_secs(5)).unwrap(),
244 11
245 );
246 }
247
248 #[tokio::test(flavor = "current_thread")]
249 async fn a_current_thread_runtime_refuses_to_be_blocked() {
250 let runtime = NodeRuntime::acquire().unwrap();
251 assert!(!runtime.is_owned());
252 assert!(!runtime.can_block());
253 let error = runtime
254 .block_on("EventStream::recv", "EventStream::recv_async", async {})
255 .unwrap_err();
256 assert!(matches!(
257 error,
258 NodeError::BlockingInAsync {
259 method: "EventStream::recv",
260 alternative: "EventStream::recv_async"
261 }
262 ));
263 assert!(error.is_usage_error());
264 }
265
266 #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
267 async fn a_multi_thread_runtime_is_borrowed_and_can_block() {
268 let runtime = NodeRuntime::acquire().unwrap();
269 assert!(!runtime.is_owned());
270 assert!(runtime.can_block());
271 let value = runtime
272 .block_on("test", "test_async", async { 3_u8 })
273 .unwrap();
274 assert_eq!(value, 3);
275 }
276
277 #[test]
278 fn an_owned_runtime_can_be_dropped_from_an_async_context() {
279 // Built outside a runtime, dropped inside one: a plain
280 // `Runtime::drop` would panic here.
281 let runtime = NodeRuntime::owned().unwrap();
282 runtime.block_on("test", "test", async {}).unwrap();
283 let inner = NodeRuntime::owned().unwrap();
284 inner
285 .block_on("test", "test", async move {
286 drop(runtime);
287 })
288 .unwrap();
289 }
290
291 #[test]
292 fn the_worker_count_is_documented() {
293 assert_eq!(OWNED_WORKER_THREADS, 2);
294 }
295}