Show how to integrate with Tracing

Turns out to be pretty simple!

Fixes #6

Author: sourcefrog

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "nutmeg"
-version = "0.1.3"
+version = "0.1.4"
 edition = "2021"
 description = "An unopinionated progress bar library"
 license = "MIT"
@@ -17,3 +17,8 @@ yansi = "0.5"
 
 [dev-dependencies]
 rand = "0.8"
+tracing = "0.1"
+tracing-subscriber = "0.3"
+
+[workspace]
+members = ["examples/tracing"]

NEWS.md

@@ -1,110 +1,114 @@
 # Nutmeg Changelog
 
+## 0.1.4
+
+- New: Support and documentation for sending `tracing` updates through a Nutmeg view.
+
 ## 0.1.3
 
 Released 2023-05-24
 
-* New: [View::clear] temporarily removes the progress view if it is drawn, but
+- New: [View::clear] temporarily removes the progress view if it is drawn, but
   allows it to pop back when the model is next updated.
 
-* New: [Options] can be constructed as a `static` value: there's a new
+- New: [Options] can be constructed as a `static` value: there's a new
   `const fn` [Options::new] constructor and the functions to set fields are also
   `const`.
 
-* New: [View::message_bytes] as a convenience for callers who already have
+- New: [View::message_bytes] as a convenience for callers who already have
   a `[u8]` or `Bytes` or similar.
 
 ## 0.1.2
 
 Released 2022-07-27
 
-* API change: Removed `View::new_stderr` and `View::write_to`. Instead, the view
+- API change: Removed `View::new_stderr` and `View::write_to`. Instead, the view
   can be drawn on stderr or output can be captured using [Options::destination].
   This is better aligned with the idea that programs might have a central function
   that constructs a [Options], as they will probably want to consistently
   write to either stdout or stderr.
 
-* New: Output can be captured for inspection in tests using [Options::destination],
+- New: Output can be captured for inspection in tests using [Options::destination],
   [Destination::Capture], and [View::captured_output].
 
-* Improved: Nutmeg avoids redrawing if the model renders identical output to what
+- Improved: Nutmeg avoids redrawing if the model renders identical output to what
   is already displayed, to avoid flicker.
 
 ## 0.1.1
 
 Released 2022-03-22
 
-* API change: [View::message] takes the message as an `AsRef<str>`, meaning
+- API change: [View::message] takes the message as an `AsRef<str>`, meaning
   it may be either a `&str` or `String`. This makes the common case where
   the message is the result of `format!` a little easier.
 
 ## 0.1.0
 
 Released 2022-03-22
 
-* API change: The "Write" type representing the destination is no longer
+- API change: The "Write" type representing the destination is no longer
   part of the visible public signature of [View], to hide complexity and
   since it is not helpful to most callers.
 
-* API change: Renamed `View::to_stderr` to `View::new_stderr`.
+- API change: Renamed `View::to_stderr` to `View::new_stderr`.
 
-* New: [percent_done] and [estimate_remaining] functions to help in rendering progress bars.
+- New: [percent_done] and [estimate_remaining] functions to help in rendering progress bars.
 
-* New: The [models] mod provides some generally-useful basic models,
+- New: The [models] mod provides some generally-useful basic models,
   specifically [models::StringPair], [models::UnboundedModel] and [models::LinearModel].
   These build only on the public interface of Nutmeg, so also constitute examples of what can be done in
   application-defined models.
 
-* New: [View::finish] removes the progress bar (if painted) and returns the [Model].
+- New: [View::finish] removes the progress bar (if painted) and returns the [Model].
   [View::abandon] now also returns the model.
 
-* New: [Model::final_message] to let the model render a message to be printed when work
+- New: [Model::final_message] to let the model render a message to be printed when work
   is complete.
 
-* New: The callback to [View::update] may return a value, and this is passed back to the caller
+- New: The callback to [View::update] may return a value, and this is passed back to the caller
   of [View::update].
 
-* New: [models::BasicModel] allows simple cases to supply both an initial value
+- New: [models::BasicModel] allows simple cases to supply both an initial value
   and a render function inline in the [View] constructor call, avoiding any
   need to define a [Model] struct.
 
-* New: [View::inspect_model] gives its callback a `&mut` to the model.
+- New: [View::inspect_model] gives its callback a `&mut` to the model.
 
-* New: Progress bars constructed by [View::new] and `View::new_stderr` are disabled when
+- New: Progress bars constructed by [View::new] and `View::new_stderr` are disabled when
   `$TERM=dumb`.
 
 ## 0.0.2
 
 Released 2022-03-07
 
-* API change: Renamed `nutmeg::ViewOptions` to just `nutmeg::Options`.
+- API change: Renamed `nutmeg::ViewOptions` to just `nutmeg::Options`.
 
-* Fixed: A bug that caused leftover text when multi-line bars shrink in width.
+- Fixed: A bug that caused leftover text when multi-line bars shrink in width.
 
-* Fixed: The output from bars created with [View::new] and `View::to_stderr` in
+- Fixed: The output from bars created with [View::new] and `View::to_stderr` in
   Rust tests is captured with the test output rather than leaking through
   to cargo's output.
 
-* New method [View::message] to print a message to the terminal, as an alternative
+- New method [View::message] to print a message to the terminal, as an alternative
   to using `write!()`.
 
-* New `example/multithreaded.rs` showing how a View and Model can be shared
+- New `example/multithreaded.rs` showing how a View and Model can be shared
   across threads.
 
 ## 0.0.1
 
-* Rate-limit updates to the terminal, controlled by
+- Rate-limit updates to the terminal, controlled by
   `ViewOptions::update_interval` and `ViewOptions::print_holdoff`.
 
-* Fix a bug where the bar was sometimes not correctly erased
+- Fix a bug where the bar was sometimes not correctly erased
   by [View::suspend].
 
-* Change to [`parking_lot`](https://docs.rs/parking_lot) mutexes in the implementation.
+- Change to [`parking_lot`](https://docs.rs/parking_lot) mutexes in the implementation.
 
 ## 0.0.0
 
-* The application has complete control of styling, including coloring etc.
-* Draw and erase progress bars.
-* Write messages "under" the progress bar with `writeln!(view, ...)`. The
+- The application has complete control of styling, including coloring etc.
+- Draw and erase progress bars.
+- Write messages "under" the progress bar with `writeln!(view, ...)`. The
   bar is automatically suspended and restored. If the message has no final
   newline, the bar remains suspended until the line is completed.

examples/tracing/.gitignore

@@ -0,0 +1 @@
+target

examples/tracing/Cargo.toml

@@ -0,0 +1,13 @@
+[package]
+name = "nutmeg-tracing-example"
+version = "0.1.0"
+edition = "2021"
+publish = false
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+nutmeg = { path = "../..", version = "*" }
+tracing = "*"
+tracing-fmt = "*"
+tracing-subscriber = "*"

examples/tracing/src/main.rs

@@ -0,0 +1,58 @@
+//! Show integration of Nutmeg and tracing: tracing console messages
+//! are interspersed nicely with the progress bar.
+
+use std::sync::Arc;
+use std::time::Instant;
+
+use nutmeg::View;
+use tracing::Level;
+use tracing_subscriber::prelude::*;
+
+fn main() {
+    let model = Model {
+        count: 0,
+        start: Instant::now(),
+    };
+    let view = Arc::new(View::new(model, nutmeg::Options::new()));
+    let layer = tracing_subscriber::fmt::layer()
+        .with_ansi(true)
+        .with_writer(Arc::clone(&view))
+        .with_target(false)
+        .with_timer(tracing_subscriber::fmt::time::uptime())
+        .with_filter(tracing_subscriber::filter::LevelFilter::from_level(
+            Level::INFO,
+        ));
+    tracing_subscriber::registry().with(layer).init();
+
+    for i in 0..100 {
+        if i % 10 == 0 {
+            tracing::info!("count: {}", i);
+        } else if i % 37 == 0 {
+            tracing::warn!(i, "spooky!");
+        }
+        view.update(|m| m.count += 1);
+        std::thread::sleep(std::time::Duration::from_millis(100));
+    }
+}
+
+struct Model {
+    count: usize,
+    start: Instant,
+}
+
+impl nutmeg::Model for Model {
+    fn render(&mut self, _width: usize) -> String {
+        let spin = match self.count % 4 {
+            0 => "|",
+            1 => "/",
+            2 => "-",
+            3 => "\\",
+            _ => unreachable!(),
+        };
+        format!(
+            "{spin} count: {}, elapsed: {:.1}s",
+            self.count,
+            self.start.elapsed().as_secs_f64()
+        )
+    }
+}

src/lib.rs

@@ -135,6 +135,53 @@ The `examples/bench.rs` sends updates as fast as possible to a model containing
 single `u64`, from a single thread. As of 2022-03-22, on a 2019 Core i9 Macbook Pro,
 it takes about 500ms to send 10e6 updates, or 50ns/update.
 
+# Integration with `tracing`
+
+Nutmeg can be used to draw progress bars in a terminal interleaved with
+[tracing](https://docs.rs/tracing/) messages. The progress bar is automatically
+temporarily removed to show messages, and repainted after the next update,
+subject to rate limiting and the holdoff time configured in [Options].
+
+`Arc<View<M>>` implicitly implements [`tracing_subscriber::fmt::writer::MakeWriter`](https://docs.rs/tracing-subscriber/0.3.17/tracing_subscriber/fmt/writer/trait.MakeWriter.html)
+and so can be passed to `tracing_subscriber::fmt::layer().with_writer()`.
+
+For example:
+
+```rust
+    use std::sync::Arc;
+    use tracing::Level;
+    use tracing_subscriber::prelude::*;
+
+    struct Model { count: usize }
+    impl nutmeg::Model for Model {
+         fn render(&mut self, _width: usize) -> String { todo!() }
+    }
+
+    let model = Model {
+        count: 0,
+    };
+    let view = Arc::new(nutmeg::View::new(model, nutmeg::Options::new()));
+    let layer = tracing_subscriber::fmt::layer()
+        .with_ansi(true)
+        .with_writer(Arc::clone(&view))
+        .with_target(false)
+        .with_timer(tracing_subscriber::fmt::time::uptime())
+        .with_filter(tracing_subscriber::filter::LevelFilter::from_level(
+            Level::INFO,
+        ));
+    tracing_subscriber::registry().with(layer).init();
+
+    for i in 0..10 {
+        if i % 10 == 0 {
+            tracing::info!(i, "cats adored");
+        }
+        view.update(|m| m.count += 1);
+        std::thread::sleep(std::time::Duration::from_millis(100));
+    }
+```
+
+See `examples/tracing` for a runnable example.
+
 # Project status
 
 Nutmeg is a young library. Although the API will not break gratuitously,
@@ -515,6 +562,19 @@ impl<M: Model> View<M> {
     }
 }
 
+impl<M: Model> io::Write for &View<M> {
+    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
+        if buf.is_empty() {
+            return Ok(0);
+        }
+        self.inner.lock().as_mut().unwrap().write(buf)
+    }
+
+    fn flush(&mut self) -> io::Result<()> {
+        Ok(())
+    }
+}
+
 impl<M: Model> io::Write for View<M> {
     fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
         if buf.is_empty() {