feat: Introduce the object-safe RawProgress trait.

It's automatically implemented for `Progress` and allows for more flexible use
of progress particularly in leaf nodes. This is useful if a function needs to take
multiple types of progress as it is called from different places in the same function.

Without dyn-traits, it's not possible to make such call.

Author: Byron

src/lib.rs

@@ -64,7 +64,7 @@ pub mod messages;
 pub mod progress;
 
 mod traits;
-pub use traits::{Progress, Root, WeakRoot};
+pub use traits::{Progress, RawProgress, Root, WeakRoot};
 
 mod throughput;
 pub use crate::throughput::Throughput;

src/traits.rs

@@ -2,7 +2,7 @@ use std::time::Instant;
 
 use crate::{messages::MessageLevel, progress, progress::Id, Unit};
 
-/// A trait for describing hierarchical process.
+/// A trait for describing hierarchical progress.
 pub trait Progress: Send {
     /// The type of progress returned by [`add_child()`][Progress::add_child()].
     type SubProgress: Progress;
@@ -154,6 +154,146 @@ pub trait Progress: Send {
     }
 }
 
+/// A trait for describing non-hierarchical progress.
+///
+/// It differs by not being able to add child progress dynamically, but in turn is object safe. It's recommended to
+/// use this trait whenever there is no need to add child progress, at the leaf of a computation.
+// NOTE: keep this in-sync with `Progress`.
+pub trait RawProgress: Send {
+    /// Initialize the Item for receiving progress information.
+    ///
+    /// If `max` is `Some(…)`, it will be treated as upper bound. When progress is [set(…)](./struct.Item.html#method.set)
+    /// it should not exceed the given maximum.
+    /// If `max` is `None`, the progress is unbounded. Use this if the amount of work cannot accurately
+    /// be determined in advance.
+    ///
+    /// If `unit` is `Some(…)`, it is used for display purposes only. See `prodash::Unit` for more information.
+    ///
+    /// If both `unit` and `max` are `None`, the item will be reset to be equivalent to 'uninitialized'.
+    ///
+    /// If this method is never called, this `Progress` instance will serve as organizational unit, useful to add more structure
+    /// to the progress tree (e.g. a headline).
+    ///
+    /// **Note** that this method can be called multiple times, changing the bounded-ness and unit at will.
+    fn init(&mut self, max: Option<progress::Step>, unit: Option<Unit>);
+
+    /// Set the current progress to the given `step`. The cost of this call is negligible,
+    /// making manual throttling *not* necessary.
+    ///
+    /// **Note**: that this call has no effect unless `init(…)` was called before.
+    fn set(&mut self, step: progress::Step);
+
+    /// Returns the (cloned) unit associated with this Progress
+    fn unit(&self) -> Option<Unit> {
+        None
+    }
+
+    /// Returns the maximum about of items we expect, as provided with the `init(…)` call
+    fn max(&self) -> Option<progress::Step> {
+        None
+    }
+
+    /// Set the maximum value to `max` and return the old maximum value.
+    fn set_max(&mut self, _max: Option<progress::Step>) -> Option<progress::Step> {
+        None
+    }
+
+    /// Returns the current step, as controlled by `inc*(…)` calls
+    fn step(&self) -> progress::Step;
+
+    /// Increment the current progress to the given `step`.
+    /// The cost of this call is negligible, making manual throttling *not* necessary.
+    fn inc_by(&mut self, step: progress::Step);
+
+    /// Increment the current progress to the given 1. The cost of this call is negligible,
+    /// making manual throttling *not* necessary.
+    fn inc(&mut self) {
+        self.inc_by(1)
+    }
+
+    /// Set the name of the instance, altering the value given when crating it with `add_child(…)`
+    /// The progress is allowed to discard it.
+    fn set_name(&mut self, name: String);
+
+    /// Get the name of the instance as given when creating it with `add_child(…)`
+    /// The progress is allowed to not be named, thus there is no guarantee that a previously set names 'sticks'.
+    fn name(&self) -> Option<String>;
+
+    /// Get a stable identifier for the progress instance.
+    /// Note that it could be [unknown][crate::progress::UNKNOWN].
+    fn id(&self) -> Id;
+
+    /// Create a `message` of the given `level` and store it with the progress tree.
+    ///
+    /// Use this to provide additional,human-readable information about the progress
+    /// made, including indicating success or failure.
+    fn message(&mut self, level: MessageLevel, message: String);
+
+    /// If available, return an atomic counter for direct access to the underlying state.
+    ///
+    /// This is useful if multiple threads want to access the same progress, without the need
+    /// for provide each their own progress and aggregating the result.
+    fn counter(&self) -> Option<StepShared> {
+        None
+    }
+
+    /// Create a message providing additional information about the progress thus far.
+    fn info(&mut self, message: String) {
+        self.message(MessageLevel::Info, message)
+    }
+    /// Create a message indicating the task is done successfully
+    fn done(&mut self, message: String) {
+        self.message(MessageLevel::Success, message)
+    }
+    /// Create a message indicating the task failed
+    fn fail(&mut self, message: String) {
+        self.message(MessageLevel::Failure, message)
+    }
+    /// A shorthand to print throughput information
+    fn show_throughput(&mut self, start: Instant) {
+        let step = self.step();
+        match self.unit() {
+            Some(unit) => self.show_throughput_with(start, step, unit, MessageLevel::Info),
+            None => {
+                let elapsed = start.elapsed().as_secs_f32();
+                let steps_per_second = (step as f32 / elapsed) as progress::Step;
+                self.info(format!(
+                    "done {} items in {:.02}s ({} items/s)",
+                    step, elapsed, steps_per_second
+                ))
+            }
+        };
+    }
+
+    /// A shorthand to print throughput information, with the given step and unit, and message level.
+    fn show_throughput_with(&mut self, start: Instant, step: progress::Step, unit: Unit, level: MessageLevel) {
+        use std::fmt::Write;
+        let elapsed = start.elapsed().as_secs_f32();
+        let steps_per_second = (step as f32 / elapsed) as progress::Step;
+        let mut buf = String::with_capacity(128);
+        let unit = unit.as_display_value();
+        let push_unit = |buf: &mut String| {
+            buf.push(' ');
+            let len_before_unit = buf.len();
+            unit.display_unit(buf, step).ok();
+            if buf.len() == len_before_unit {
+                buf.pop();
+            }
+        };
+
+        buf.push_str("done ");
+        unit.display_current_value(&mut buf, step, None).ok();
+        push_unit(&mut buf);
+
+        buf.write_fmt(format_args!(" in {:.02}s (", elapsed)).ok();
+        unit.display_current_value(&mut buf, steps_per_second, None).ok();
+        push_unit(&mut buf);
+        buf.push_str("/s)");
+
+        self.message(level, buf);
+    }
+}
+
 use crate::{
     messages::{Message, MessageCopyState},
     progress::StepShared,
@@ -205,12 +345,90 @@ mod impls {
         time::Instant,
     };
 
+    use crate::traits::RawProgress;
     use crate::{
         messages::MessageLevel,
         progress::{Id, Step, StepShared},
         Progress, Unit,
     };
 
+    impl<T> RawProgress for T
+    where
+        T: Progress,
+    {
+        fn init(&mut self, max: Option<Step>, unit: Option<Unit>) {
+            <T as Progress>::init(self, max, unit)
+        }
+
+        fn set(&mut self, step: Step) {
+            <T as Progress>::set(self, step)
+        }
+
+        fn unit(&self) -> Option<Unit> {
+            <T as Progress>::unit(self)
+        }
+
+        fn max(&self) -> Option<Step> {
+            <T as Progress>::max(self)
+        }
+
+        fn set_max(&mut self, max: Option<Step>) -> Option<Step> {
+            <T as Progress>::set_max(self, max)
+        }
+
+        fn step(&self) -> Step {
+            <T as Progress>::step(self)
+        }
+
+        fn inc_by(&mut self, step: Step) {
+            <T as Progress>::inc_by(self, step)
+        }
+
+        fn inc(&mut self) {
+            <T as Progress>::inc(self)
+        }
+
+        fn set_name(&mut self, name: String) {
+            <T as Progress>::set_name(self, name)
+        }
+
+        fn name(&self) -> Option<String> {
+            <T as Progress>::name(self)
+        }
+
+        fn id(&self) -> Id {
+            <T as Progress>::id(self)
+        }
+
+        fn message(&mut self, level: MessageLevel, message: String) {
+            <T as Progress>::message(self, level, message)
+        }
+
+        fn counter(&self) -> Option<StepShared> {
+            <T as Progress>::counter(self)
+        }
+
+        fn info(&mut self, message: String) {
+            <T as Progress>::info(self, message)
+        }
+
+        fn done(&mut self, message: String) {
+            <T as Progress>::done(self, message)
+        }
+
+        fn fail(&mut self, message: String) {
+            <T as Progress>::fail(self, message)
+        }
+
+        fn show_throughput(&mut self, start: Instant) {
+            <T as Progress>::show_throughput(self, start)
+        }
+
+        fn show_throughput_with(&mut self, start: Instant, step: Step, unit: Unit, level: MessageLevel) {
+            <T as Progress>::show_throughput_with(self, start, step, unit, level)
+        }
+    }
+
     impl<'a, T> Progress for &'a mut T
     where
         T: Progress,
@@ -266,7 +484,7 @@ mod impls {
         }
 
         fn id(&self) -> Id {
-            todo!()
+            self.deref().id()
         }
 
         fn message(&mut self, level: MessageLevel, message: impl Into<String>) {

tests/prodash.rs

@@ -1,2 +1,3 @@
 mod progress;
+mod raw_progress;
 mod unit;

tests/raw_progress/mod.rs

@@ -0,0 +1,11 @@
+use prodash::RawProgress;
+
+#[test]
+fn dyn_safe() {
+    fn needs_dyn(_p: &mut dyn RawProgress) {}
+    let root = prodash::tree::Root::new();
+    let mut child = root.add_child("hello");
+    needs_dyn(&mut child);
+    let mut child_of_child = child.add_child("there");
+    needs_dyn(&mut child_of_child);
+}