Struct ConcurrentWrapper

pub struct ConcurrentWrapper<P: ProgressLog = ProgressLogger> { /* private fields */ }

A concurrent wrapper for a ProgressLog implementation.

This struct wraps a ProgressLog in such as way that multiple thread can write to it. Writes are synchronized using a mutex, but they are also buffered using a given threshold, so the mutex is not accessed too often.

Once a ConcurrentWrapper is created, one can clone it to create any number of copies using the same underlying logger.

The methods update and update_with_count buffer the increment and add it to the underlying logger only when the buffer reaches a threshold; this prevents locking the underlying logger too often. The threshold is set at creation using the methods with_threshold and wrap_with_threshold, or by calling the method threshold.

The method light_update, as in the case of ProgressLogger, further delays updates using an even faster check.

You can create a duplicate of a concurrent wrapper, which will use a cloned inner logger.

Examples

use dsi_progress_logger::prelude::*;
use std::thread;

let mut cpl = concurrent_progress_logger![item_name = "pumpkin"];
cpl.start("Smashing pumpkins (using many threads)...");

std::thread::scope(|s| {
    for i in 0..100 {
        let mut pl = cpl.clone();
        s.spawn(move || {
            for _ in 0..100000 {
                pl.update();
            }
        });
    }
});

cpl.done();

Implementations

impl ConcurrentWrapper

pub fn new() -> Self

Create a new ConcurrentWrapper based on a default ProgressLogger, using the default threshold.

pub fn with_threshold(threshold: u32) -> Self

Create a new ConcurrentWrapper wrapping a default ProgressLogger, using the given threshold.

impl<P: ProgressLog> ConcurrentWrapper<P>

pub const DEFAULT_THRESHOLD: u32 = 32_768u32

The default threshold for updating the underlying logger.

pub const LIGHT_UPDATE_MASK: u32 = 1_023u32

Calls to light_update will cause a call to update_with_count only if the current local count is a multiple of this mask plus one.

Note that this constant is significantly smaller than the one used in ProgressLogger, as updates will be further delayed by the threshold mechanism.

pub fn threshold(&mut self, threshold: u32) -> &mut Self

Set the threshold for updating the underlying logger.

Note concurrent loggers with the same underlying logger have independent thresholds.

pub fn wrap(inner: P) -> Self

Wrap a given ProgressLog in a ConcurrentWrapper using the default threshold.

pub fn wrap_with_threshold(inner: P, threshold: u32) -> Self

Wrap a given ProgressLog in a ConcurrentWrapper using a given threshold.

pub fn flush(&mut self)

Force an update of the underlying logger with the current local count.

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

pub fn dup(&self) -> Self

Clone the concurrent wrapper, obtaning a new one with the same threshold, with a local count of zero, and with an inner ProgressLog that is a clone of the original one.

Note that the this method has the same sematics of ProgressLogser’s Clone implementation, but it is much more ergonomic here to have cloning to generate copies with the same underlying logger.

Trait Implementations

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

Clone the concurrent wrapper, obtaning a new one with the same threshold, with a local count of zero, and the same inner ProgressLog.

The resulting logger can be passed to other threads to perform concurrent progress logging.

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Default for ConcurrentWrapper

Create a new ConcurrentWrapper based on a default ProgressLogger, with a threshold of DEFAULT_THRESHOLD.

fn default() -> Self

Returns the “default value” for a type.

impl Display for ConcurrentWrapper

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<P: ProgressLog> Drop for ConcurrentWrapper<P>

This implementation just calls flush, to guarantee that all updates are correctly passed to the underlying logger.

fn drop(&mut self)

Executes the destructor for this type.

impl<P: ProgressLog> ProgressLog for ConcurrentWrapper<P>

fn log(&mut self, now: Instant)

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

fn log_if(&mut self)

Log self if it is time to log.

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

Set the display of memory information.

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.

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

Set the time unit to use for speed.

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.

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

Start the logger, displaying the given message.

fn update(&mut self)

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

fn update_with_count(&mut self, count: usize)

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

fn light_update(&mut self)

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

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.

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

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

fn refresh(&mut self)

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

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

Output the given message.