Module dqcsim::common::log

A log thread and thread-local log proxy combination.

This module provides logging functionality to run a dedicated log thread in combination with one or more thread-local log proxy instances. The log thread provides the endpoint used by the log proxy instances to send their log records. Log proxy instances run in different threads or child processes.

Usage

Start by spawning a LogThread from the main thread. Next, initialize a LogProxy instance per thread or child process. A log LogRecord can be generated using the provided macros. The thread-local LogProxy forwards the records to the LogThread for logging.

LogThread

The LogThread is the sink for all log Records. It can output log records to Standard Error output and invoke a LogCallback function. Both these options can be enabled by setting the corresponding LogLevelFilter above LogLevelFilter::Off. Incoming log Records are forwarded to Standard Error output or to the LogCallback function if their Loglevel is equal or below the configured LogLevelFilter.

LogCallback

A LogThread can invoke a LogCallback function for incoming records. This is enabled by passing a LogCallback (with a LoglevelFilter bigger than LogLevelFilter::Off) to the callback argument of the spawn method of LogThread.

LogProxy

A LogProxy forwards log Records to a LogThread. It logs records with it's logger name if the generated log LogRecord Loglevel is smaller or equal than the configured LoglevelFilter of the LogProxy.

TeeFile

A TeeFile forwards log Records to a file. It logs records with it's logger name if the generated log LogRecord Loglevel is smaller or equal than the configured LoglevelFilter of the TeeFile.

Basic Example

use dqcsim::{
    debug,
    common::log::{init, proxy::LogProxy, thread::LogThread, LoglevelFilter},
    note,
};

// Spawn the log thread. This starts a thread-local log proxy in the main
// thread with a Note level filter and "main_thread" as name. This example
// enables Standard Error output at Debug level filter.
let log_thread = LogThread::spawn(
    "main_thread",
    LoglevelFilter::Note,
    LoglevelFilter::Debug,
    None,
    vec![]
)
.unwrap();

// Grab a copy of the log thread sender to use in the log proxy.
let log_endpoint = log_thread.get_sender();

// Spawn an other thread.
std::thread::spawn(move || {
    // Construct a log proxy instance which connects to the log thread endpoint.
    let log_proxy = LogProxy::boxed("other_thread", LoglevelFilter::Trace, log_endpoint);

    // Initialize the thread-local logger to enable forwarding of log records to
    // the log thread.
    init(vec![log_proxy]);

    // Generate a log record
    note!("Note from thread via proxy");
})
.join();

// This log records is also forwarded to the log thread by the log proxy running
// in the main thread.
debug!("Note from main thread via proxy started by log_thread spawn function");

Inspired by

• log
• sfackler's comment

Modules

callback
proxy	A generic log proxy implementation.
stdio	Utility function to spawn a log proxy implementation to forward standard i/o streams.
tee_file
thread	A log thread implementation.

Structs

LogRecord	A log record.
LoglevelFilterIter
LoglevelIter
Metadata	Log record metadata.
NoLoglevel

Enums

Loglevel	Loglevel for log records.
LoglevelFilter	LoglevelFilter for implementors of the Log trait.

Constants

LOGGERS

The thread-local loggers.

Traits

Log	The Log trait.

Functions

deinit	Deinitialize the thread-local loggers.
init	Initialize the thread-local loggers.