Trait ProgressLog

pub trait ProgressLog {
    type Concurrent: ConcurrentProgressLog;

    // Required methods
    fn log(&mut self, now: Instant);
    fn log_if(&mut self, now: Instant);
    fn display_memory(&mut self, display_memory: bool) -> &mut Self;
    fn item_name(&mut self, item_name: impl AsRef<str>) -> &mut Self;
    fn log_interval(&mut self, log_interval: Duration) -> &mut Self;
    fn expected_updates(&mut self, expected_updates: Option<usize>) -> &mut Self;
    fn time_unit(&mut self, time_unit: Option<TimeUnit>) -> &mut Self;
    fn local_speed(&mut self, local_speed: bool) -> &mut Self;
    fn log_target(&mut self, target: impl AsRef<str>) -> &mut Self;
    fn add_to_count(&mut self, count: usize);
    fn start(&mut self, msg: impl AsRef<str>);
    fn update(&mut self);
    fn update_with_count_and_time(&mut self, count: usize, now: Instant);
    fn light_update(&mut self);
    fn update_and_display(&mut self);
    fn stop(&mut self);
    fn done(&mut self);
    fn done_with_count(&mut self, count: usize);
    fn elapsed(&self) -> Option<Duration>;
    fn count(&self) -> usize;
    fn refresh(&mut self);
    fn trace(&self, args: Arguments<'_>);
    fn debug(&self, args: Arguments<'_>);
    fn info(&self, args: Arguments<'_>);
    fn warn(&self, args: Arguments<'_>);
    fn error(&self, args: Arguments<'_>);
    fn concurrent(&self) -> Self::Concurrent;

    // Provided method
    fn update_with_count(&mut self, count: usize) { ... }
}

Logging trait.

To log the progress of an activity, you call start. Then, each time you want to mark progress, you call update, which increases the item counter, and will log progress information if enough time has passed since the last log. light_update will perform a time check only on a subset of updates (e.g., for ProgressLogger, multiples of LIGHT_UPDATE_MASK + 1); it should be used when the activity has an extremely low cost that is comparable to that of the time check (a call to Instant::now()) itself.

A few setters can be called at any time to customize the logger (e.g., item_name, log_interval, expected_updates, etc.). The setters take and return a mutable reference to the logger, so you must first assign the logger to a variable, and then you can chain-call the setters on the variable in fluent style. The disadvantage of this approach is that you must assign the logger to a variable, but the advantage is that you can call any setter without having to reassign the variable holding the logger.

It is also possible to log used and free memory at each log interval by calling display_memory. Memory is read from system data by the sysinfo crate, and will be updated at each log interval (note that this will slightly slow down the logging process). However, never use this feature in a rayon environment if another crate in your compilation unit depends on on sysinfo’s (default) multithread feature, as this can lead to a deadlock .

At any time, displaying the progress logger will give you time information up to the present. However, since it is impossible to update the memory information from the Display::fmt implementation, you should call refresh before displaying the logger on your own.

When the activity is over, you call stop, which fixes the final time, and possibly display again the logger. done will stop the logger, print Completed., and display the final stats.

After you finish a run of the progress logger, can call start again measure another activity.

As explained in the crate documentation, we suggest using &mut impl ProgressLog to pass a logger as an argument, to be able to use optional logging.

Examples

See the ProgressLogger documentation.

Required Associated Types

type Concurrent: ConcurrentProgressLog

The type returned by concurrent.

Required Methods

fn log(&mut self, now: Instant)

Force a log of self assuming now is the current time.

This is a low-level method that should not be called directly.

fn log_if(&mut self, now: Instant)

Log self if it is time to log.

This is a low-level method that should not be called directly.

fn display_memory(&mut self, display_memory: bool) -> &mut Self

Set the display of memory information.

Memory information include:

• the resident-set size of the process that created the logger;
• the virtual-memory size of the process that created the logger;
• the available memory;
• the free memory;
• the total amount of memory.

Never use this feature in a rayon environment if another crate in your compilation unit depends on on sysinfo’s (default) multithread feature, as this can lead to a deadlock .

fn item_name(&mut self, item_name: impl AsRef<str>) -> &mut Self

Set the name of an item.

fn log_interval(&mut self, log_interval: Duration) -> &mut Self

Set the log interval.

fn expected_updates(&mut self, expected_updates: Option<usize>) -> &mut Self

Set the expected number of updates.

If not None, the logger will display the percentage of completion and an estimate of the time to completion.

fn time_unit(&mut self, time_unit: Option<TimeUnit>) -> &mut Self

Set the time unit to use for speed.

If not None, the logger will always display the speed in this unit instead of making a choice of readable unit based on the elapsed time. Moreover, large numbers will not be thousands separated. This behavior is useful when the output of the logger must be parsed.

fn local_speed(&mut self, local_speed: bool) -> &mut Self

Set whether to display additionally the speed achieved during the last log interval.

fn log_target(&mut self, target: impl AsRef<str>) -> &mut Self

Set the log target.

This should often be the path of the module logging progress, which is obtained with std::module_path!.

Note that the macro progress_logger! sets this field automatically to std::module_path!.

Examples

use dsi_progress_logger::prelude::*;

   env_logger::builder()
       .filter_level(log::LevelFilter::Info)
       .try_init()?;

let mut pl = ProgressLogger::default();
pl.item_name("pumpkin");
pl.log_target(std::module_path!());
pl.start("Smashing pumpkins from a module...");
for _ in 0..100 {
   // do something on each pumpkin
   pl.update();
}
pl.done();

fn add_to_count(&mut self, count: usize)

Add a value to the counter.

This method is mainly useful for wrappers or to implement a custom update strategy.

fn start(&mut self, msg: impl AsRef<str>)

Start the logger, displaying the given message.

You can pass the empty string to display nothing.

fn update(&mut self)

Increase the count and check whether it is time to log.

fn update_with_count_and_time(&mut self, count: usize, now: Instant)

Set the count and check whether it is time to log, given the current time.

This method is mainly useful for wrappers that want to avoid unnecessary calls to Instant::now.

fn light_update(&mut self)

Increase the count but checks whether it is time to log only after an implementation-defined number of calls.

Useful for very short activities with respect to which checking the time is expensive.

fn update_and_display(&mut self)

Increase the count and forces a log.

fn stop(&mut self)

Stop the logger, fixing the final time.

fn done(&mut self)

Stop the logger, print Completed., and display the final stats. The number of expected updates will be cleared.

fn done_with_count(&mut self, count: usize)

Stop the logger, sets the count, prints Completed., and displays the final stats. The number of expected updates will be cleared.

This method is particularly useful in two circumstances:

• you have updated the logger with some approximate values (e.g., in a multicore computation) but before printing the final stats you want the internal counter to contain an exact value;
• you have used the logger as a handy timer, calling just start and this method.

fn elapsed(&self) -> Option<Duration>

Return the elapsed time since the logger was started, or None if the logger has not been started.

fn count(&self) -> usize

Return the last count the logger has been set to.

Note that you can call this method even after the logger has been stopped.

fn refresh(&mut self)

Refresh memory information, if previously requested with display_memory. You do not need to call this method unless you display the logger manually.

fn trace(&self, args: Arguments<'_>)

Output the given message at the trace level.

See info for an example.

fn debug(&self, args: Arguments<'_>)

Output the given message at the debug level.

See info for an example.

fn info(&self, args: Arguments<'_>)

Output the given message at the info level.

For maximum flexibility, this method takes as argument the result of a std::format_args! macro. Note that there will be no output if the logger is None.

Examples

use dsi_progress_logger::*;

env_logger::builder()
    .filter_level(log::LevelFilter::Info)
    .try_init()?;

let logger_name = "my_logger";
let mut pl = progress_logger![];
pl.info(format_args!("My logger named {}", logger_name));

fn warn(&self, args: Arguments<'_>)

Output the given message at the warn level.

See info for an example.

fn error(&self, args: Arguments<'_>)

Output the given message at the error level.

See info for an example.

fn concurrent(&self) -> Self::Concurrent

Return a concurrent copy of the logger.

Some methods require both sequential and concurrent logging. To keep optional logging efficient, we suggest in this cases to use &mut impl ProgressLog to pass a logger as an argument, and then creating a concurrent copy of the logger with this method. If the original logger is None, the concurrent copy will be None as well.

Note that the result of the method is a copy—it will not share the state of the original logger.

Concurrent logger implementations can just return a duplicate of themselves. dup.

Provided Methods

fn update_with_count(&mut self, count: usize)

Set the count and check whether it is time to log.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementations on Foreign Types

impl<P: ProgressLog> ProgressLog for Option<P>

fn local_speed(&mut self, local_speed: bool) -> &mut Self

Sets whether to display additionally the speed achieved during the last log interval.

type Concurrent = Option<<P as ProgressLog>::Concurrent>

fn log(&mut self, now: Instant)

fn log_if(&mut self, now: Instant)

fn add_to_count(&mut self, count: usize)

fn display_memory(&mut self, display_memory: bool) -> &mut Self

fn item_name(&mut self, item_name: impl AsRef<str>) -> &mut Self

fn log_interval(&mut self, log_interval: Duration) -> &mut Self

fn expected_updates(&mut self, expected_updates: Option<usize>) -> &mut Self

fn time_unit(&mut self, time_unit: Option<TimeUnit>) -> &mut Self

fn log_target(&mut self, target: impl AsRef<str>) -> &mut Self

fn start(&mut self, msg: impl AsRef<str>)

fn update(&mut self)

fn update_with_count_and_time(&mut self, count: usize, now: Instant)

fn light_update(&mut self)

fn update_and_display(&mut self)

fn stop(&mut self)

fn done(&mut self)

fn done_with_count(&mut self, count: usize)

fn elapsed(&self) -> Option<Duration>

fn count(&self) -> usize

fn refresh(&mut self)

fn trace(&self, args: Arguments<'_>)

fn debug(&self, args: Arguments<'_>)

fn info(&self, args: Arguments<'_>)

fn warn(&self, args: Arguments<'_>)

fn error(&self, args: Arguments<'_>)

fn concurrent(&self) -> Self::Concurrent

impl<P: ProgressLog> ProgressLog for &mut P

type Concurrent = <P as ProgressLog>::Concurrent

fn log(&mut self, now: Instant)

fn log_if(&mut self, now: Instant)

fn add_to_count(&mut self, count: usize)

fn display_memory(&mut self, display_memory: bool) -> &mut Self

fn item_name(&mut self, item_name: impl AsRef<str>) -> &mut Self

fn log_interval(&mut self, log_interval: Duration) -> &mut Self

fn expected_updates(&mut self, expected_updates: Option<usize>) -> &mut Self

fn time_unit(&mut self, time_unit: Option<TimeUnit>) -> &mut Self

fn local_speed(&mut self, local_speed: bool) -> &mut Self

fn log_target(&mut self, target: impl AsRef<str>) -> &mut Self

fn start(&mut self, msg: impl AsRef<str>)

fn update(&mut self)

fn update_with_count_and_time(&mut self, count: usize, now: Instant)

fn light_update(&mut self)

fn update_and_display(&mut self)

fn stop(&mut self)

fn done(&mut self)

fn done_with_count(&mut self, count: usize)

fn elapsed(&self) -> Option<Duration>

fn count(&self) -> usize

fn refresh(&mut self)

fn trace(&self, args: Arguments<'_>)

fn debug(&self, args: Arguments<'_>)

fn info(&self, args: Arguments<'_>)

fn warn(&self, args: Arguments<'_>)

fn error(&self, args: Arguments<'_>)

fn concurrent(&self) -> Self::Concurrent

Implementors

impl ProgressLog for ProgressLogger

type Concurrent = ConcurrentWrapper

impl<P: ProgressLog + Clone + Send> ProgressLog for ConcurrentWrapper<P>

type Concurrent = ConcurrentWrapper<P>