use std::fmt;
use std::io::{self, Write};
use std::num::NonZeroU8;
use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
use std::sync::{Arc, Mutex};
use indicatif::{ProgressBar, ProgressDrawTarget, ProgressStyle, TermLike};
use crate::console_api::DestinationState;
use crate::render::render_text;
use crate::{ConsoleError, HumanText, Stream, Theme, TokenId};
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct ProgressOptions {
pub length: Option<u64>,
pub message_token: TokenId,
pub message: HumanText,
pub refresh_hz: NonZeroU8,
}
pub struct ProgressHandle {
id: u64,
bar: ProgressBar,
hidden: bool,
destination: Arc<DestinationState>,
theme: Theme,
errors: Arc<Mutex<Option<io::Error>>>,
released: bool,
}
impl ProgressHandle {
pub fn is_hidden(&self) -> bool {
self.hidden
}
pub fn set_message(
&self,
token: TokenId,
message: impl AsRef<str>,
) -> Result<(), ConsoleError> {
let message = HumanText::sanitize(message);
self.destination.progress.mutate(|| {
self.bar.set_message(render_progress_message(
&self.destination,
&self.theme,
&token,
&message,
));
take_error(&self.errors)
})
}
pub fn set_position(&self, position: u64) -> Result<(), ConsoleError> {
self.destination.progress.mutate(|| {
self.bar.set_position(position);
take_error(&self.errors)
})
}
pub fn inc(&self, delta: u64) -> Result<(), ConsoleError> {
self.destination.progress.mutate(|| {
self.bar.inc(delta);
take_error(&self.errors)
})
}
pub fn finish(mut self, token: TokenId, message: impl AsRef<str>) -> Result<(), ConsoleError> {
let message = HumanText::sanitize(message);
let result = self.destination.progress.complete(self.id, || {
self.bar.finish_with_message(render_progress_message(
&self.destination,
&self.theme,
&token,
&message,
));
take_error(&self.errors)
});
self.released = true;
result
}
pub fn clear(mut self) -> Result<(), ConsoleError> {
let result = self.destination.progress.complete(self.id, || {
self.bar.finish_and_clear();
take_error(&self.errors)
});
self.released = true;
result
}
}
impl Drop for ProgressHandle {
fn drop(&mut self) {
if self.released {
return;
}
let _ = self.destination.progress.complete(self.id, || {
self.bar.finish_and_clear();
let _ = take_error(&self.errors);
Ok(())
});
self.released = true;
}
}
#[derive(Clone)]
struct ActiveProgress {
id: u64,
bar: ProgressBar,
errors: Arc<Mutex<Option<io::Error>>>,
}
pub(crate) struct ProgressCoordinator {
operation: Mutex<()>,
active: Mutex<Option<ActiveProgress>>,
has_active: AtomicBool,
next_id: AtomicU64,
#[cfg(test)]
suspension_count: AtomicU64,
}
impl ProgressCoordinator {
pub(crate) fn new() -> Self {
Self {
operation: Mutex::new(()),
active: Mutex::new(None),
has_active: AtomicBool::new(false),
next_id: AtomicU64::new(1),
#[cfg(test)]
suspension_count: AtomicU64::new(0),
}
}
fn release_locked(&self, id: u64) {
let mut active = self
.active
.lock()
.unwrap_or_else(|poisoned| poisoned.into_inner());
let matches_id = matches!(active.as_ref(), Some(progress) if progress.id == id);
if matches_id {
*active = None;
self.has_active.store(false, Ordering::Release);
}
}
fn initialize<T>(
&self,
build: impl FnOnce(u64) -> Result<(ProgressBar, Arc<Mutex<Option<io::Error>>>, T), ConsoleError>,
) -> Result<T, ConsoleError> {
let _operation = self
.operation
.lock()
.unwrap_or_else(|poisoned| poisoned.into_inner());
if self
.active
.lock()
.unwrap_or_else(|poisoned| poisoned.into_inner())
.is_some()
{
return Err(ConsoleError::ProgressAlreadyActive);
}
self.has_active.store(true, Ordering::Release);
let id = self.next_id.fetch_add(1, Ordering::Relaxed);
let (bar, errors, value) = match build(id) {
Ok(built) => built,
Err(error) => {
self.has_active.store(false, Ordering::Release);
return Err(error);
}
};
*self
.active
.lock()
.unwrap_or_else(|poisoned| poisoned.into_inner()) =
Some(ActiveProgress { id, bar, errors });
Ok(value)
}
fn mutate(
&self,
operation: impl FnOnce() -> Result<(), ConsoleError>,
) -> Result<(), ConsoleError> {
let _serial = self
.operation
.lock()
.unwrap_or_else(|poisoned| poisoned.into_inner());
operation()
}
fn complete(
&self,
id: u64,
operation: impl FnOnce() -> Result<(), ConsoleError>,
) -> Result<(), ConsoleError> {
let _serial = self
.operation
.lock()
.unwrap_or_else(|poisoned| poisoned.into_inner());
let result = operation();
self.release_locked(id);
result
}
pub(crate) fn suspend(
&self,
operation: impl FnOnce() -> Result<(), ConsoleError>,
) -> Result<(), ConsoleError> {
if !self.has_active.load(Ordering::Acquire) {
return operation();
}
let _serial = self
.operation
.lock()
.unwrap_or_else(|poisoned| poisoned.into_inner());
let active = self
.active
.lock()
.unwrap_or_else(|poisoned| poisoned.into_inner())
.clone();
let Some(active) = active else {
return operation();
};
#[cfg(test)]
self.suspension_count.fetch_add(1, Ordering::Relaxed);
let result = active.bar.suspend(operation);
let backend_result = take_error(&active.errors);
match result {
Err(error) => Err(error),
Ok(()) => backend_result,
}
}
#[cfg(test)]
fn take_suspension_count(&self) -> u64 {
self.suspension_count.swap(0, Ordering::Relaxed)
}
}
pub(crate) fn start(
destination: Arc<DestinationState>,
theme: Theme,
options: ProgressOptions,
) -> Result<ProgressHandle, ConsoleError> {
let coordinator = destination.progress.clone();
coordinator.initialize(|id| {
let hidden = !destination.options.terminal.interactive_cursor;
let errors = Arc::new(Mutex::new(None));
let target = if hidden {
ProgressDrawTarget::hidden()
} else {
let adapter = SinkTermLike {
sink: destination.sink.clone(),
width: destination
.options
.terminal
.width
.map_or(80, |width| width.get()),
errors: errors.clone(),
};
ProgressDrawTarget::term_like_with_hz(Box::new(adapter), options.refresh_hz.get())
};
let bar = ProgressBar::with_draw_target(options.length, target);
let template = if options.length.is_some() {
"{spinner} {msg} {pos}/{len}"
} else {
"{spinner} {msg}"
};
let style = ProgressStyle::with_template(template)
.map_err(|source| ConsoleError::Write {
stream: Stream::Stderr,
source: io::Error::new(io::ErrorKind::InvalidInput, source.to_string()),
})?
.tick_strings(&["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏", "✔"]);
bar.set_style(style);
bar.set_message(render_progress_message(
&destination,
&theme,
&options.message_token,
&options.message,
));
take_error(&errors)?;
let handle = ProgressHandle {
id,
bar: bar.clone(),
hidden,
destination,
theme,
errors: errors.clone(),
released: false,
};
Ok((bar, errors, handle))
})
}
fn render_progress_message(
destination: &DestinationState,
theme: &Theme,
token: &TokenId,
message: &HumanText,
) -> String {
render_text(
theme,
token,
message.as_str(),
destination.options.terminal.color_depth,
destination.color_enabled,
Stream::Stderr,
)
}
fn take_error(errors: &Arc<Mutex<Option<io::Error>>>) -> Result<(), ConsoleError> {
let error = errors
.lock()
.unwrap_or_else(|poisoned| poisoned.into_inner())
.take();
match error {
Some(source) => Err(ConsoleError::Write {
stream: Stream::Stderr,
source,
}),
None => Ok(()),
}
}
struct SinkTermLike {
sink: Arc<Mutex<Box<dyn Write + Send>>>,
width: u16,
errors: Arc<Mutex<Option<io::Error>>>,
}
impl fmt::Debug for SinkTermLike {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("SinkTermLike")
.field("width", &self.width)
.finish_non_exhaustive()
}
}
impl SinkTermLike {
fn write_with(
&self,
operation: impl FnOnce(&mut dyn Write) -> io::Result<()>,
) -> io::Result<()> {
let result = {
let mut sink = self
.sink
.lock()
.unwrap_or_else(|poisoned| poisoned.into_inner());
operation(sink.as_mut())
};
if let Err(error) = &result {
let mut slot = self
.errors
.lock()
.unwrap_or_else(|poisoned| poisoned.into_inner());
if slot.is_none() {
*slot = Some(io::Error::new(error.kind(), error.to_string()));
}
}
result
}
fn cursor(&self, count: usize, suffix: char) -> io::Result<()> {
if count == 0 {
return Ok(());
}
self.write_with(|sink| write!(sink, "\x1b[{count}{suffix}"))
}
}
impl TermLike for SinkTermLike {
fn width(&self) -> u16 {
self.width
}
fn move_cursor_up(&self, count: usize) -> io::Result<()> {
self.cursor(count, 'A')
}
fn move_cursor_down(&self, count: usize) -> io::Result<()> {
self.cursor(count, 'B')
}
fn move_cursor_right(&self, count: usize) -> io::Result<()> {
self.cursor(count, 'C')
}
fn move_cursor_left(&self, count: usize) -> io::Result<()> {
self.cursor(count, 'D')
}
fn write_line(&self, value: &str) -> io::Result<()> {
self.write_with(|sink| {
sink.write_all(value.as_bytes())?;
sink.write_all(b"\n")
})
}
fn write_str(&self, value: &str) -> io::Result<()> {
self.write_with(|sink| sink.write_all(value.as_bytes()))
}
fn clear_line(&self) -> io::Result<()> {
self.write_with(|sink| sink.write_all(b"\r\x1b[2K"))
}
fn flush(&self) -> io::Result<()> {
self.write_with(|sink| sink.flush())
}
}
#[cfg(test)]
mod tests {
use super::*;
use std::num::NonZeroU16;
use crate::{
Alignment, Cell, ColorChoice, ColorDepth, Console, ConsoleOptions, DestinationOptions, Doc,
FixedColumn, FixedTable, FixedTableOptions, OutputClass, Overflow, Span,
TerminalCapabilities, tokens,
};
#[derive(Clone, Default)]
struct Capture(Arc<Mutex<Vec<u8>>>);
impl Write for Capture {
fn write(&mut self, bytes: &[u8]) -> io::Result<usize> {
self.0
.lock()
.unwrap_or_else(|poisoned| poisoned.into_inner())
.extend_from_slice(bytes);
Ok(bytes.len())
}
fn flush(&mut self) -> io::Result<()> {
Ok(())
}
}
fn hidden_console() -> Console {
let capabilities = TerminalCapabilities {
is_terminal: false,
color_depth: ColorDepth::Ansi16,
width: NonZeroU16::new(20),
interactive_cursor: false,
};
Console::with_writers(
Capture::default(),
Capture::default(),
ConsoleOptions {
stdout: DestinationOptions {
output_class: OutputClass::Human,
color: ColorChoice::Never,
terminal: capabilities,
},
stderr: DestinationOptions {
output_class: OutputClass::Human,
color: ColorChoice::Never,
terminal: capabilities,
},
theme: crate::themes::default(),
},
)
.expect("valid hidden console")
}
fn options() -> ProgressOptions {
ProgressOptions {
length: Some(10),
message_token: tokens::PROGRESS,
message: HumanText::sanitize("working"),
refresh_hz: NonZeroU8::new(10).expect("nonzero"),
}
}
fn inject_error(errors: &Arc<Mutex<Option<io::Error>>>) {
*errors
.lock()
.unwrap_or_else(|poisoned| poisoned.into_inner()) = Some(io::Error::new(
io::ErrorKind::BrokenPipe,
"injected adapter failure",
));
}
#[test]
fn every_human_operation_uses_one_whole_progress_suspension() {
let console = hidden_console();
let handle = console.stderr_progress(options()).expect("progress");
let mut writer = console.human(Stream::Stderr).expect("human stderr");
writer
.spans(&[Span::new(tokens::TEXT, "span")])
.expect("spans");
assert_eq!(console.stderr.progress.take_suspension_count(), 1);
assert_eq!(console.stderr.take_lock_count(), 1);
writer
.line(&[Span::new(tokens::TEXT, "line")])
.expect("line");
assert_eq!(console.stderr.progress.take_suspension_count(), 1);
assert_eq!(console.stderr.take_lock_count(), 1);
writer.blank_line().expect("blank line");
assert_eq!(console.stderr.progress.take_suspension_count(), 1);
assert_eq!(console.stderr.take_lock_count(), 1);
writer
.doc(&Doc::concat([
Doc::text("first"),
Doc::hard_line(),
Doc::text("second"),
]))
.expect("document");
assert_eq!(console.stderr.progress.take_suspension_count(), 1);
assert_eq!(console.stderr.take_lock_count(), 1);
let columns = [FixedColumn {
width: NonZeroU16::new(4).expect("nonzero"),
alignment: Alignment::Left,
overflow: Overflow::Clip,
}];
let mut table = FixedTable::new(columns, FixedTableOptions::default()).expect("table");
table.row([Cell::new("one", tokens::TEXT)]);
table.row([Cell::new("two", tokens::TEXT)]);
writer.fixed_table(&table).expect("fixed table");
assert_eq!(console.stderr.progress.take_suspension_count(), 1);
assert_eq!(console.stderr.take_lock_count(), 1);
#[cfg(feature = "adaptive-tables")]
{
let mut table = crate::AdaptiveTable::new(
vec![crate::AdaptiveColumn {
min_width: NonZeroU16::new(2).expect("nonzero"),
max_width: NonZeroU16::new(8).expect("nonzero"),
alignment: Alignment::Left,
}],
NonZeroU16::new(8).expect("nonzero"),
)
.expect("adaptive table");
table
.row(vec![Cell::new("adaptive content", tokens::TEXT)])
.expect("row");
writer.adaptive_table(&table).expect("adaptive table");
assert_eq!(console.stderr.progress.take_suspension_count(), 1);
assert_eq!(console.stderr.take_lock_count(), 1);
}
handle.clear().expect("clear");
}
#[test]
fn lifecycle_operations_hold_the_serialization_guard_for_their_full_extent() {
let coordinator = ProgressCoordinator::new();
let id = coordinator
.initialize(|id| {
assert!(coordinator.operation.try_lock().is_err());
assert!(
coordinator
.active
.lock()
.unwrap_or_else(|poisoned| poisoned.into_inner())
.is_none()
);
Ok((ProgressBar::hidden(), Arc::new(Mutex::new(None)), id))
})
.expect("initialize progress");
coordinator
.mutate(|| {
assert!(coordinator.operation.try_lock().is_err());
Ok(())
})
.expect("mutate progress");
coordinator
.suspend(|| {
assert!(coordinator.operation.try_lock().is_err());
Ok(())
})
.expect("suspend progress");
coordinator
.complete(id, || {
assert!(coordinator.operation.try_lock().is_err());
Ok(())
})
.expect("complete progress");
assert!(
coordinator
.active
.lock()
.unwrap_or_else(|poisoned| poisoned.into_inner())
.is_none()
);
}
#[test]
fn adapter_error_slot_is_drained_on_mutation_suspension_finish_clear_and_drop() {
let console = hidden_console();
let handle = console.stderr_progress(options()).expect("progress");
inject_error(&handle.errors);
assert!(matches!(
handle.set_position(1),
Err(ConsoleError::Write {
stream: Stream::Stderr,
..
})
));
inject_error(&handle.errors);
assert!(matches!(
handle.set_message(tokens::PROGRESS, "updated"),
Err(ConsoleError::Write {
stream: Stream::Stderr,
..
})
));
inject_error(&handle.errors);
assert!(matches!(
handle.inc(1),
Err(ConsoleError::Write {
stream: Stream::Stderr,
..
})
));
handle.inc(1).expect("drained after mutations");
inject_error(&handle.errors);
assert!(matches!(
console
.human(Stream::Stderr)
.expect("writer")
.line(&[Span::new(tokens::TEXT, "diagnostic")]),
Err(ConsoleError::Write {
stream: Stream::Stderr,
..
})
));
console
.human(Stream::Stderr)
.expect("writer")
.line(&[Span::new(tokens::TEXT, "recovered")])
.expect("drained after suspension");
inject_error(&handle.errors);
assert!(matches!(
handle.finish(tokens::STATUS_SUCCESS, "done"),
Err(ConsoleError::Write {
stream: Stream::Stderr,
..
})
));
let handle = console.stderr_progress(options()).expect("slot released");
inject_error(&handle.errors);
assert!(matches!(
handle.clear(),
Err(ConsoleError::Write {
stream: Stream::Stderr,
..
})
));
let handle = console.stderr_progress(options()).expect("slot released");
inject_error(&handle.errors);
drop(handle);
console
.stderr_progress(options())
.expect("drop releases and drains")
.clear()
.expect("no stale draw error");
}
}