Progress Bars in R via indicatif
miniextendr provides an adapter that routes indicatif progress bar output through R's console, so progress bars render correctly in R terminals, RStudio, and other R frontends.
miniextendr provides an adapter that routes indicatif progress bar output through R’s console, so progress bars render correctly in R terminals, RStudio, and other R frontends.
Feature flag: indicatif (implies nonapi)
[dependencies]
miniextendr-api = { version = "0.1", features = ["indicatif"] }🔗Table of Contents
- Why a Custom Terminal Adapter
- Quick Start
- RTerm
- Convenience Constructors
- Refresh Rate Tuning
- Main Thread Safety
- ANSI Cursor Support
- Complete Example
- Limitations
🔗Why a Custom Terminal Adapter
R’s console output is not stdout or stderr. R uses its own output functions (Rprintf, REprintf, or the ptr_R_WriteConsoleEx hook) to route text to the active frontend (terminal, RStudio, Jupyter, etc.). Writing directly to stdout/stderr would bypass R entirely – output might not appear in RStudio’s console, or could interleave incorrectly with R’s own output.
indicatif’s ProgressBar needs a TermLike implementation to know how to write text, move the cursor, and clear lines. RTerm implements TermLike by routing all output through R’s console hooks, making indicatif work seamlessly inside R.
🔗Quick Start
use miniextendr_api::progress::term_like_stderr;
use indicatif::{ProgressBar, ProgressStyle};
use miniextendr_api::miniextendr;
#[miniextendr]
pub fn process_data(x: &[f64]) -> Vec<f64> {
let pb = ProgressBar::with_draw_target(Some(x.len() as u64), term_like_stderr(80));
pb.set_style(
ProgressStyle::with_template("{bar:40} {pos}/{len} [{elapsed_precise}]").unwrap()
);
let result: Vec<f64> = x.iter().map(|&val| {
pb.inc(1);
val.sqrt()
}).collect();
pb.finish_with_message("done");
result
}
From R:
result <- process_data(runif(100000))
#> ======================================== 100000/100000 [00:00:01]🔗RTerm
RTerm is the TermLike implementation. It takes an R connection and a fixed
column width: RStdout or RStderr for R’s console, or any other connection
object passed in from R.
use miniextendr_api::connection::RStderr;
use miniextendr_api::progress::RTerm;
use indicatif::ProgressDrawTarget;
let term = RTerm::new(RStderr, 80);
let target = ProgressDrawTarget::term_like(Box::new(term));
Use stderr() for progress bars (the conventional choice), so they don’t
interfere with data piped to stdout. The width parameter controls how
indicatif formats the progress bar. Use 80 as a safe default. If you need
dynamic width detection, query getOption("width") from R and pass it in.
🔗Output Routing
R’s terminal connections (stdout(), stderr()) go through R’s console:
- Primary:
ptr_R_WriteConsoleEx– the hook used by R frontends (RStudio, Jupyter, etc.) - Fallback:
Rprintf/REprintf– standard R output functions (used when the hook is unavailable)
All console output is chunked to respect i32::MAX byte limits per call, and
NUL bytes are stripped from the fallback path. The console does not consult
sink(), so a bar drawn to stderr() stays on the console.
Any other connection (file(), rawConnection(), a custom Rust connection)
gets the bytes through its write callback: R_WriteConnection, or before
R 4.6 writeBin() / writeChar() (see CONNECTIONS.md, “R
versions before 4.6”). R’s errors are caught there: when the connection has
been closed, or its write fails, the draw returns an io::Error and indicatif
skips it. The bar, and any other bar, keeps working. textConnection() has no
write callback, so drawing to one fails the same way.
🔗Convenience Constructors
For common use cases, these functions create ProgressDrawTarget values directly:
use miniextendr_api::progress::*;
// Basic targets (default refresh rate)
let target = term_like_stdout(80);
let target = term_like_stderr(80);
let target = term_like_connection(conn, 80); // `conn`: a connection from R
// With custom refresh rate
let target = term_like_stdout_with_hz(80, 10);
let target = term_like_stderr_with_hz(80, 10);
let target = term_like_connection_with_hz(conn, 80, 10);
All return ProgressDrawTarget, ready to pass to ProgressBar::with_draw_target().
🔗Refresh Rate Tuning
The _with_hz variants let you control how often indicatif redraws the progress bar:
// Update at 5 Hz (every 200ms) - less overhead for slow connections
let target = term_like_stderr_with_hz(80, 5);
// Update at 20 Hz (every 50ms) - smoother appearance for fast operations
let target = term_like_stderr_with_hz(80, 20);| Scenario | Suggested Hz |
|---|---|
| Long-running computation (minutes) | 2-5 |
| Medium operations (seconds) | 10 (default) |
| Fast operations where smoothness matters | 15-20 |
| Remote / slow terminal connections | 2-3 |
Higher refresh rates mean more R console calls, which adds overhead. For tight loops where each iteration is very fast, consider using pb.inc(batch_size) to update in batches rather than increasing the refresh rate.
🔗Main Thread Safety
All RTerm output is silently dropped when called from a non-main thread:
fn write_console(&self, bytes: &[u8]) -> io::Result<()> {
if !crate::is_r_main_thread() {
return Ok(()); // Silent no-op
}
// ... actual output ...
}
This means:
- Progress bars drawn from non-main threads (rayon threads, spawned threads) produce no output.
- Only code running on the main R thread can display progress.
For #[miniextendr] functions, this works naturally – your function runs on the main
thread, so progress bar output works directly. Since indicatif batches draws, the simplest
approach is to create the progress bar and call pb.inc() from your function directly.
When the work itself runs on another thread, have it send its progress to the main thread
and draw there: WorkerPump runs the work on a worker thread and calls a pump closure on
the main thread for each message the worker sends, so pb.inc() goes in the pump:
use miniextendr_api::pump::WorkerPump;
let total = WorkerPump::<u64>::new()
.run(
|tx| {
let mut total = 0;
for chunk in &chunks {
total += process(chunk); // pure Rust, no R API
if tx.send(1).is_err() {
break;
}
}
Ok(total)
},
|done| pb.inc(done), // R's main thread
)
.map_err(|e| e.to_string())?;
pb.finish();
See THREADS.md for the main-thread invariant and “Progress from a worker
thread (WorkerPump)” there for how an R error in the pump stops the worker.
🔗ANSI Cursor Support
RTerm implements all cursor movement operations via ANSI escape sequences:
| Operation | ANSI Sequence | Method |
|---|---|---|
| Move cursor up N lines | \x1b[NA | move_cursor_up(n) |
| Move cursor down N lines | \x1b[NB | move_cursor_down(n) |
| Move cursor right N columns | \x1b[NC | move_cursor_right(n) |
| Move cursor left N columns | \x1b[ND | move_cursor_left(n) |
| Clear current line | \r\x1b[2K | clear_line() |
These work in terminals that support ANSI escape codes (most modern terminals, including macOS Terminal, iTerm2, and the RStudio terminal pane). The flush() method calls R_FlushConsole() to ensure output is displayed immediately.
🔗Complete Example
A #[miniextendr] function with a styled progress bar:
use miniextendr_api::miniextendr;
use miniextendr_api::progress::term_like_stderr;
use indicatif::{ProgressBar, ProgressStyle};
#[miniextendr]
pub fn compute_with_progress(n: i32) -> Vec<f64> {
let n = n as usize;
let pb = ProgressBar::with_draw_target(Some(n as u64), term_like_stderr(80));
pb.set_style(
ProgressStyle::with_template(
"{spinner:.green} [{elapsed_precise}] [{bar:40.cyan/blue}] {pos}/{len} ({eta})"
)
.unwrap()
.progress_chars("=>-")
);
let mut results = Vec::with_capacity(n);
for i in 0..n {
// Simulate expensive computation
let value = ((i as f64) * 0.001).sin().powi(2);
results.push(value);
pb.inc(1);
}
pb.finish_with_message("computation complete");
results
}
From R:
result <- compute_with_progress(1000000L)
#> / [00:00:02] [========================================] 1000000/1000000 (0s)🔗Multi-Progress Bar Example
indicatif’s MultiProgress works too:
use indicatif::{MultiProgress, ProgressBar, ProgressStyle};
use miniextendr_api::connection::RStderr;
use miniextendr_api::progress::RTerm;
#[miniextendr]
pub fn parallel_progress() {
let term = RTerm::new(RStderr, 80);
let mp = MultiProgress::with_draw_target(
indicatif::ProgressDrawTarget::term_like(Box::new(term))
);
let style = ProgressStyle::with_template("{prefix:.bold} {bar:30} {pos}/{len}").unwrap();
let pb1 = mp.add(ProgressBar::new(100));
pb1.set_style(style.clone());
pb1.set_prefix("Task 1");
let pb2 = mp.add(ProgressBar::new(200));
pb2.set_style(style);
pb2.set_prefix("Task 2");
for i in 0..200 {
if i < 100 { pb1.inc(1); }
pb2.inc(1);
}
pb1.finish();
pb2.finish();
}🔗Limitations
- Main thread only. Output from non-main threads is silently dropped. This is by design – R’s console functions are not thread-safe.
- Fixed width.
RTermuses a fixed column width (no dynamic terminal size detection). Pass the desired width when constructing. - ANSI support varies. RStudio’s console pane has limited ANSI support. Multi-line progress bars may not render correctly in all R frontends. Single-line progress bars work everywhere.
- No input.
RTermis output-only. It cannot read user input (e.g., for interactive prompts). - Non-interactive sessions. In
Rscriptor batch mode (R CMD BATCH), console output may be buffered or suppressed depending on the frontend. Progress bars still work but may not display in real-time. - Implies
nonapi. Theindicatiffeature enables thenonapifeature becauseptr_R_WriteConsoleExis a non-API symbol. This meansR CMD checkwill note the use of non-API entry points.
🔗See Also
- FEATURES.md – Feature flags reference (
indicatif) - THREADS.md – The main-thread invariant
- indicatif documentation – Full indicatif API reference