Enum WriteMode

pub enum WriteMode {
    Direct,
    SupportCapture,
    BufferAndFlush,
    BufferAndFlushWith(usize, Duration),
    BufferDontFlush,
    BufferDontFlushWith(usize),
    Async,
    AsyncWith {
        pool_capa: usize,
        message_capa: usize,
        flush_interval: Duration,
    },
}

Describes whether the log output should be written synchronously or asynchronously, and if and how I/O should be buffered and flushed.

Is used in Logger::write_mode.

Buffering reduces the program’s I/O overhead, and thus increases overall performance, which can become relevant if logging is used heavily. On the other hand, if logging is used with low frequency, buffering can defer the appearance of log lines significantly, so regular flushing is usually advisable with buffering.

Note that for all options except Direct you should keep the LoggerHandle alive up to the very end of your program to ensure that all buffered log lines are flushed out (which happens automatically when the LoggerHandle is dropped) before the program terminates. See here for an example.

Note further that flushing uses an extra thread (with minimal stack).

The console is a slow output device (at least on Windows). With WriteMode::Async it can happen that in phases with vast log output the log lines appear significantly later than they were written. Also, a final printing phase is possible at the end of the program when the logger handle is dropped (and all output is flushed automatically).

WriteMode::Direct (i.e. without buffering) is the slowest option with all output devices, showing that buffered I/O pays off.

Using log_to_stdout() and then redirecting the output to a file can make things faster, likely because the operating system’s adds buffering, but is still significantly slower than writing to files directly.

Variants

Direct

Do not buffer (default).

Every log line is directly written to the output, without buffering. This allows seeing new log lines in real time, and does not need additional threads.

SupportCapture

Do not buffer and support cargo test’s capture.

Much like Direct, just a bit slower, and allows cargo test to capture log output and print it only for failing tests.

BufferAndFlush

Same as BufferAndFlushWith with default capacity (DEFAULT_BUFFER_CAPACITY) and default interval (DEFAULT_FLUSH_INTERVAL).

BufferAndFlushWith(usize, Duration)

Buffer and flush with given buffer capacity and flush interval.

Tuple Fields

0: usize

Buffer capacity.

1: Duration

Flush interval.

BufferDontFlush

Same as BufferDontFlushWith with default capacity (DEFAULT_BUFFER_CAPACITY).

BufferDontFlushWith(usize)

Buffer with given buffer capacity, but don’t flush.

This might be handy if you want to minimize I/O effort and don’t want to create the extra thread for flushing and don’t care if log lines appear with delay.

Tuple Fields

0: usize

Buffer capacity.

Async

Available on crate feature async only.

Same as AsyncWith, using default values for all parameters.

AsyncWith

Available on crate feature async only.

Log lines are sent through an unbounded channel to an output thread, which does the I/O, and, if log_to_file() is chosen, also the rotation and the cleanup.

Uses buffered output to reduce overhead, and a bounded message pool to reduce allocations. The log output is flushed regularly with the given interval.

See here for an example.

Fields

pool_capa: usize

Capacity of the pool for the message buffers.

message_capa: usize

Capacity of an individual message buffer.

flush_interval: Duration

The interval for flushing the output.

With Duration::ZERO flushing is suppressed.

Trait Implementations

impl Clone for WriteMode

fn clone(&self) -> WriteMode

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for WriteMode

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

Formats the value using the given formatter.

impl PartialEq for WriteMode

fn eq(&self, other: &WriteMode) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Copy for WriteMode

impl Eq for WriteMode

impl StructuralPartialEq for WriteMode