Skip to main content

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