Skip to main content

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}