miniextendr_api/pump.rs
1//! [`WorkerPump<T>`] — safe main/worker thread coordination for FFI bodies.
2//!
3//! # Overview
4//!
5//! `WorkerPump` manages the common pattern of running a CPU-bound worker on a
6//! background thread while the main R thread drives a "pump" loop — processing
7//! progress events, rendering output, or any other operation that must happen
8//! on R's main thread (e.g. calls into R's C API).
9//!
10//! It wraps [`std::thread::scope`] so the worker is always joined before
11//! `run` returns, and exposes a builder API for common knobs (channel capacity,
12//! log-drain cadence).
13//!
14//! # R exits in the pump
15//!
16//! Call `WorkerPump::run` from an `#[miniextendr]` body, on R's main thread,
17//! and have the pump call R only through the APIs that turn an R exit into a
18//! Rust unwind: [`RCall::eval_with_handlers`] /
19//! [`RCall::try_eval_with_handlers`] (and `Quoted::eval` /
20//! `Quosure::eval_tidy`, which use them).
21//!
22//! When R leaves such a call early (an error, a `tryCatch()` exit, an
23//! interrupt while R runs), it unwinds as a Rust panic carrying the R exit.
24//! The unwind runs through `run`: the receiver drops, so the worker's next
25//! `send` returns `Err`, and [`std::thread::scope`] joins the worker before
26//! the unwind leaves it. The `#[miniextendr]` boundary then continues the R
27//! exit, so the condition reaches the function's caller.
28//!
29//! R must never `longjmp` over `run` instead: a bare `Rf_eval` / `Rf_error`
30//! in the pump jumps past `run`'s frames without running their destructors,
31//! so the worker, which borrows from them, is never joined.
32//!
33//! The worker should stop when `send` returns `Err`: one that keeps computing
34//! delays the R exit until it returns.
35//!
36//! [`RCall::eval_with_handlers`]: crate::expression::RCall::eval_with_handlers
37//! [`RCall::try_eval_with_handlers`]: crate::expression::RCall::try_eval_with_handlers
38//!
39//! # Error type
40//!
41//! `WorkerPump::run` uses `Result<R, Box<dyn Error + Send + Sync>>` so it
42//! composes naturally with both `anyhow::Result` (via `?`) and `std::io::Error`
43//! without requiring a hard dependency on any error-handling crate.
44//!
45//! # Example
46//!
47//! ```rust,ignore
48//! use miniextendr_api::pump::WorkerPump;
49//! use std::sync::mpsc::SyncSender;
50//!
51//! #[miniextendr]
52//! fn compress_files(paths: Vec<String>) -> i64 {
53//! WorkerPump::new()
54//! .run(
55//! // worker: runs off-main-thread
56//! |tx: SyncSender<u64>| -> Result<i64, Box<dyn std::error::Error + Send + Sync>> {
57//! let mut total = 0i64;
58//! for path in &paths {
59//! let bytes = compress_one(path)?;
60//! tx.send(bytes).ok();
61//! total += bytes as i64;
62//! }
63//! Ok(total)
64//! },
65//! // pump: runs on main thread, may call R API
66//! |bytes| render_progress(bytes),
67//! )
68//! .expect("compression failed")
69//! }
70//! ```
71
72use std::error::Error;
73use std::marker::PhantomData;
74use std::sync::mpsc::{self, SyncSender};
75use std::thread;
76
77/// Boxed, thread-safe error type used by [`WorkerPump::run`].
78///
79/// Alias for `Box<dyn Error + Send + Sync>`. Compatible with `anyhow::Error`
80/// via `?` and with standard library error types without requiring extra
81/// dependencies.
82pub type WorkerError = Box<dyn Error + Send + Sync>;
83
84/// Runs a worker thread in parallel with a main-thread pump loop.
85///
86/// See [the module documentation][self] for how an R exit in the pump stops
87/// the worker, and for a usage example.
88pub struct WorkerPump<T> {
89 /// Capacity of the bounded MPSC channel between worker and pump.
90 capacity: usize,
91 /// Whether to drain the cross-thread log queue on every pump tick.
92 drain_logs_each_tick: bool,
93 _marker: PhantomData<fn() -> T>,
94}
95
96impl<T: Send + 'static> WorkerPump<T> {
97 /// Create a new `WorkerPump` with default settings.
98 ///
99 /// Defaults:
100 /// - channel capacity: 64
101 /// - `drain_logs_each_tick`: `true`
102 pub fn new() -> Self {
103 Self {
104 capacity: 64,
105 drain_logs_each_tick: true,
106 _marker: PhantomData,
107 }
108 }
109
110 /// Set the capacity of the bounded MPSC channel.
111 ///
112 /// The default is 64. A larger capacity allows the worker to get further
113 /// ahead of the pump; a capacity of 0 makes every send synchronous
114 /// (rendezvous channel).
115 ///
116 /// When the channel is full the worker blocks on `tx.send` until the pump
117 /// drains a slot. If the pump panics, or an R exit unwinds out of it,
118 /// `rx` is dropped as part of scope unwinding, which unblocks `tx.send`
119 /// with an `Err` and lets the worker exit cleanly.
120 pub fn channel_capacity(mut self, n: usize) -> Self {
121 self.capacity = n;
122 self
123 }
124
125 /// Control whether the cross-thread log queue is drained on every pump tick.
126 ///
127 /// Default: `true`. Set to `false` if the consumer manages its own log
128 /// drain cadence (e.g. it calls `drain_log_queue()` explicitly at
129 /// coarser granularity).
130 ///
131 /// Has no effect when the `log` feature is disabled.
132 pub fn drain_logs_each_tick(mut self, on: bool) -> Self {
133 self.drain_logs_each_tick = on;
134 self
135 }
136
137 /// Run the worker/pump pair and return the worker's result.
138 ///
139 /// - `worker` runs on a scoped background thread. It receives a
140 /// [`SyncSender<T>`] and sends messages to the pump. When `worker`
141 /// returns (success or error) it should drop `tx`; the pump's receive
142 /// loop then terminates naturally.
143 /// - `pump` is called on the **current (main R) thread** for every message
144 /// the worker sends.
145 ///
146 /// `run` returns `Ok(R)` on success, or `Err` if the worker returned an
147 /// error or panicked.
148 ///
149 /// # Panics
150 ///
151 /// If the worker thread panics, `run` returns
152 /// `Err("WorkerPump worker panicked")`.
153 ///
154 /// If the pump closure panics (an R exit through
155 /// [`RCall::eval_with_handlers`](crate::expression::RCall::eval_with_handlers)
156 /// included), [`std::thread::scope`] joins the worker and the panic then
157 /// propagates out of `run`. The `#[miniextendr]` boundary turns a panic
158 /// into an R error and continues an R exit.
159 pub fn run<R, W, P>(self, worker: W, mut pump: P) -> Result<R, WorkerError>
160 where
161 R: Send,
162 W: FnOnce(SyncSender<T>) -> Result<R, WorkerError> + Send,
163 P: FnMut(T),
164 {
165 thread::scope(|scope| {
166 let (tx, rx) = mpsc::sync_channel(self.capacity);
167 let handle = scope.spawn(move || worker(tx));
168 for msg in rx {
169 if self.drain_logs_each_tick {
170 #[cfg(feature = "log")]
171 crate::optionals::log_impl::drain_log_queue();
172 }
173 pump(msg);
174 }
175 handle
176 .join()
177 .map_err(|_| -> WorkerError { "WorkerPump worker panicked".into() })?
178 })
179 }
180}
181
182impl<T: Send + 'static> Default for WorkerPump<T> {
183 fn default() -> Self {
184 Self::new()
185 }
186}
187
188// region: Tests
189
190#[cfg(test)]
191mod tests;
192
193// endregion