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: impl Into<Option<usize>>,
    ) -> &mut Self;
    fn time_unit(&mut self, time_unit: impl Into<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 push_log_target(&mut self, suffix: impl AsRef<str>) -> &mut Self;
    fn pop_log_target(&mut self) -> &mut Self;
    fn log_level(&mut self, log_level: Level) -> &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 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)

Forces 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)

Logs 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

Sets the display of memory information.

Memory information includes:

• 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 sysinfo’s (default) multithread feature, as this can lead to a deadlock .

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

Sets the name of an item.

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

Sets the log interval.

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

Sets the expected number of updates.

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

Note that there is no need to use a Some wrapper around the argument, as the method will automatically convert it to an Option type.

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

Sets 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.

Note that there is no need to use a Some wrapper around the argument, as the method will automatically convert it to an Option type.

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

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

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

Sets 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!.

Calling this method clears any suffixes previously pushed with push_log_target.

Examples

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 push_log_target(&mut self, suffix: impl AsRef<str>) -> &mut Self

Pushes a suffix to the log target.

The suffix is appended to the current log target as-is, with no separator. The caller controls the format (e.g., " > subtask" or "::phase2").

Each push records the current length of the log target so that pop_log_target can restore it.

Examples

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();

// Entering subtask
pl.push_log_target(" > smoothing");
pl.start("Smashing pumpkins...");
for _ in 0..100 {
   // do something on each pumpkin
   pl.update();
}
pl.done();
pl.pop_log_target();

fn pop_log_target(&mut self) -> &mut Self

Pops the last suffix pushed with push_log_target.

If no suffix has been pushed, this method is a no-op.

fn log_level(&mut self, log_level: Level) -> &mut Self

Sets the log level used for progress messages.

By default, progress messages are logged at the Info level.

fn add_to_count(&mut self, count: usize)

Adds 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>)

Starts the logger, displaying the given message.

An empty string can be passed to display nothing.

fn update(&mut self)

Increases the count and checks whether it is time to log.

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

Sets the count and checks 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)

Increases 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)

Increases the count and forces a log.

fn stop(&mut self)

Stops the logger, fixing the final time.

fn done(&mut self)

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

fn done_with_count(&mut self, count: usize)

Stops 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:

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

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

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

fn count(&self) -> usize

Returns the last count the logger has been set to.

Note that this method can be called even after the logger has been stopped.

fn refresh(&mut self)

Refreshes memory information, if previously requested with display_memory. There is no need to call this method unless the logger is displayed manually.

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

Outputs the given message at the trace level.

See info for an example.

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

Outputs the given message at the debug level.

See info for an example.

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

Outputs 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

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<'_>)

Outputs the given message at the warn level.

See info for an example.

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

Outputs the given message at the error level.

See info for an example.

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

Returns a concurrent copy of the logger.

Some methods require both sequential and concurrent logging. To keep optional logging efficient, it is suggested to use &mut impl ProgressLog to pass a logger as an argument, and then create 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 via dup.

Provided Methods

fn update_with_count(&mut self, count: usize)

Sets the count and checks 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>

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: impl Into<Option<usize>>, ) -> &mut Self

fn time_unit(&mut self, time_unit: impl Into<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 push_log_target(&mut self, suffix: impl AsRef<str>) -> &mut Self

fn pop_log_target(&mut self) -> &mut Self

fn log_level(&mut self, log_level: Level) -> &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: impl Into<Option<usize>>, ) -> &mut Self

fn time_unit(&mut self, time_unit: impl Into<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 push_log_target(&mut self, suffix: impl AsRef<str>) -> &mut Self

fn pop_log_target(&mut self) -> &mut Self

fn log_level(&mut self, log_level: Level) -> &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>