Enum flexi_logger::WriteMode
source · pub enum WriteMode {
Direct,
BufferAndFlush,
BufferAndFlushWith(usize, Duration),
BufferDontFlush,
BufferDontFlushWith(usize),
Async,
AsyncWith {
bufsize: usize,
pool_capa: usize,
message_capa: usize,
flush_interval: Duration,
},
}
Expand description
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. But it takes slightly more resources, especially
if you do not suppress flushing.
Using log_to_stdout()
and then redirecting the output to a file makes things faster,
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.
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.
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.
Async
Same as AsyncWith
, using default values for all parameters.
AsyncWith
Fields
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.