[rustc.git] / vendor / log / src / lib.rs

// Copyright 2015 The Rust Project Developers. See the COPYRIGHT\r
// file at the top-level directory of this distribution and at\r
// http://rust-lang.org/COPYRIGHT.\r
//\r
// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or\r
// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license\r
// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your\r
// option. This file may not be copied, modified, or distributed\r
// except according to those terms.\r
\r
//! A lightweight logging facade.\r
//!\r
//! The `log` crate provides a single logging API that abstracts over the\r
//! actual logging implementation. Libraries can use the logging API provided\r
//! by this crate, and the consumer of those libraries can choose the logging\r
//! implementation that is most suitable for its use case.\r
//!\r
//! If no logging implementation is selected, the facade falls back to a "noop"\r
//! implementation that ignores all log messages. The overhead in this case\r
//! is very small - just an integer load, comparison and jump.\r
//!\r
//! A log request consists of a _target_, a _level_, and a _body_. A target is a\r
//! string which defaults to the module path of the location of the log request,\r
//! though that default may be overridden. Logger implementations typically use\r
//! the target to filter requests based on some user configuration.\r
//!\r
//! # Usage\r
//!\r
//! The basic use of the log crate is through the five logging macros: [`error!`],\r
//! [`warn!`], [`info!`], [`debug!`] and [`trace!`]\r
//! where `error!` represents the highest-priority log messages\r
//! and `trace!` the lowest. The log messages are filtered by configuring\r
//! the log level to exclude messages with a lower priority.\r
//! Each of these macros accept format strings similarly to [`println!`].\r
//!\r
//!\r
//! [`error!`]: ./macro.error.html\r
//! [`warn!`]: ./macro.warn.html\r
//! [`info!`]: ./macro.info.html\r
//! [`debug!`]: ./macro.debug.html\r
//! [`trace!`]: ./macro.trace.html\r
//! [`println!`]: https://doc.rust-lang.org/stable/std/macro.println.html\r
//!\r
//! ## In libraries\r
//!\r
//! Libraries should link only to the `log` crate, and use the provided\r
//! macros to log whatever information will be useful to downstream consumers.\r
//!\r
//! ### Examples\r
//!\r
//! ```edition2018\r
//! # #[derive(Debug)] pub struct Yak(String);\r
//! # impl Yak { fn shave(&mut self, _: u32) {} }\r
//! # fn find_a_razor() -> Result<u32, u32> { Ok(1) }\r
//! use log::{info, warn};\r
//!\r
//! pub fn shave_the_yak(yak: &mut Yak) {\r
//!     info!(target: "yak_events", "Commencing yak shaving for {:?}", yak);\r
//!\r
//!     loop {\r
//!         match find_a_razor() {\r
//!             Ok(razor) => {\r
//!                 info!("Razor located: {}", razor);\r
//!                 yak.shave(razor);\r
//!                 break;\r
//!             }\r
//!             Err(err) => {\r
//!                 warn!("Unable to locate a razor: {}, retrying", err);\r
//!             }\r
//!         }\r
//!     }\r
//! }\r
//! # fn main() {}\r
//! ```\r
//!\r
//! ## In executables\r
//!\r
//! Executables should choose a logging implementation and initialize it early in the\r
//! runtime of the program. Logging implementations will typically include a\r
//! function to do this. Any log messages generated before\r
//! the implementation is initialized will be ignored.\r
//!\r
//! The executable itself may use the `log` crate to log as well.\r
//!\r
//! ### Warning\r
//!\r
//! The logging system may only be initialized once.\r
//!\r
//! ## Structured logging\r
//!\r
//! If you enable the `kv_unstable` feature you can associate structured values\r
//! with your log records. If we take the example from before, we can include\r
//! some additional context besides what's in the formatted message:\r
//!\r
//! ```edition2018\r
//! # #[macro_use] extern crate serde;\r
//! # #[derive(Debug, Serialize)] pub struct Yak(String);\r
//! # impl Yak { fn shave(&mut self, _: u32) {} }\r
//! # fn find_a_razor() -> Result<u32, std::io::Error> { Ok(1) }\r
//! # #[cfg(feature = "kv_unstable_serde")]\r
//! # fn main() {\r
//! use log::{info, warn, as_serde, as_error};\r
//!\r
//! pub fn shave_the_yak(yak: &mut Yak) {\r
//!     info!(target: "yak_events", yak = as_serde!(yak); "Commencing yak shaving");\r
//!\r
//!     loop {\r
//!         match find_a_razor() {\r
//!             Ok(razor) => {\r
//!                 info!(razor = razor; "Razor located");\r
//!                 yak.shave(razor);\r
//!                 break;\r
//!             }\r
//!             Err(err) => {\r
//!                 warn!(err = as_error!(err); "Unable to locate a razor, retrying");\r
//!             }\r
//!         }\r
//!     }\r
//! }\r
//! # }\r
//! # #[cfg(not(feature = "kv_unstable_serde"))]\r
//! # fn main() {}\r
//! ```\r
//!\r
//! # Available logging implementations\r
//!\r
//! In order to produce log output executables have to use\r
//! a logger implementation compatible with the facade.\r
//! There are many available implementations to choose from,\r
//! here are some of the most popular ones:\r
//!\r
//! * Simple minimal loggers:\r
//!     * [env_logger]\r
//!     * [simple_logger]\r
//!     * [simplelog]\r
//!     * [pretty_env_logger]\r
//!     * [stderrlog]\r
//!     * [flexi_logger]\r
//! * Complex configurable frameworks:\r
//!     * [log4rs]\r
//!     * [fern]\r
//! * Adaptors for other facilities:\r
//!     * [syslog]\r
//!     * [slog-stdlog]\r
//!     * [systemd-journal-logger]\r
//!     * [android_log]\r
//!     * [win_dbg_logger]\r
//!     * [db_logger]\r
//! * For WebAssembly binaries:\r
//!     * [console_log]\r
//! * For dynamic libraries:\r
//!     * You may need to construct an FFI-safe wrapper over `log` to initialize in your libraries\r
//!\r
//! # Implementing a Logger\r
//!\r
//! Loggers implement the [`Log`] trait. Here's a very basic example that simply\r
//! logs all messages at the [`Error`][level_link], [`Warn`][level_link] or\r
//! [`Info`][level_link] levels to stdout:\r
//!\r
//! ```edition2018\r
//! use log::{Record, Level, Metadata};\r
//!\r
//! struct SimpleLogger;\r
//!\r
//! impl log::Log for SimpleLogger {\r
//!     fn enabled(&self, metadata: &Metadata) -> bool {\r
//!         metadata.level() <= Level::Info\r
//!     }\r
//!\r
//!     fn log(&self, record: &Record) {\r
//!         if self.enabled(record.metadata()) {\r
//!             println!("{} - {}", record.level(), record.args());\r
//!         }\r
//!     }\r
//!\r
//!     fn flush(&self) {}\r
//! }\r
//!\r
//! # fn main() {}\r
//! ```\r
//!\r
//! Loggers are installed by calling the [`set_logger`] function. The maximum\r
//! log level also needs to be adjusted via the [`set_max_level`] function. The\r
//! logging facade uses this as an optimization to improve performance of log\r
//! messages at levels that are disabled. It's important to set it, as it\r
//! defaults to [`Off`][filter_link], so no log messages will ever be captured!\r
//! In the case of our example logger, we'll want to set the maximum log level\r
//! to [`Info`][filter_link], since we ignore any [`Debug`][level_link] or\r
//! [`Trace`][level_link] level log messages. A logging implementation should\r
//! provide a function that wraps a call to [`set_logger`] and\r
//! [`set_max_level`], handling initialization of the logger:\r
//!\r
//! ```edition2018\r
//! # use log::{Level, Metadata};\r
//! # struct SimpleLogger;\r
//! # impl log::Log for SimpleLogger {\r
//! #   fn enabled(&self, _: &Metadata) -> bool { false }\r
//! #   fn log(&self, _: &log::Record) {}\r
//! #   fn flush(&self) {}\r
//! # }\r
//! # fn main() {}\r
//! use log::{SetLoggerError, LevelFilter};\r
//!\r
//! static LOGGER: SimpleLogger = SimpleLogger;\r
//!\r
//! pub fn init() -> Result<(), SetLoggerError> {\r
//!     log::set_logger(&LOGGER)\r
//!         .map(|()| log::set_max_level(LevelFilter::Info))\r
//! }\r
//! ```\r
//!\r
//! Implementations that adjust their configurations at runtime should take care\r
//! to adjust the maximum log level as well.\r
//!\r
//! # Use with `std`\r
//!\r
//! `set_logger` requires you to provide a `&'static Log`, which can be hard to\r
//! obtain if your logger depends on some runtime configuration. The\r
//! `set_boxed_logger` function is available with the `std` Cargo feature. It is\r
//! identical to `set_logger` except that it takes a `Box<Log>` rather than a\r
//! `&'static Log`:\r
//!\r
//! ```edition2018\r
//! # use log::{Level, LevelFilter, Log, SetLoggerError, Metadata};\r
//! # struct SimpleLogger;\r
//! # impl log::Log for SimpleLogger {\r
//! #   fn enabled(&self, _: &Metadata) -> bool { false }\r
//! #   fn log(&self, _: &log::Record) {}\r
//! #   fn flush(&self) {}\r
//! # }\r
//! # fn main() {}\r
//! # #[cfg(feature = "std")]\r
//! pub fn init() -> Result<(), SetLoggerError> {\r
//!     log::set_boxed_logger(Box::new(SimpleLogger))\r
//!         .map(|()| log::set_max_level(LevelFilter::Info))\r
//! }\r
//! ```\r
//!\r
//! # Compile time filters\r
//!\r
//! Log levels can be statically disabled at compile time via Cargo features. Log invocations at\r
//! disabled levels will be skipped and will not even be present in the resulting binary.\r
//! This level is configured separately for release and debug builds. The features are:\r
//!\r
//! * `max_level_off`\r
//! * `max_level_error`\r
//! * `max_level_warn`\r
//! * `max_level_info`\r
//! * `max_level_debug`\r
//! * `max_level_trace`\r
//! * `release_max_level_off`\r
//! * `release_max_level_error`\r
//! * `release_max_level_warn`\r
//! * `release_max_level_info`\r
//! * `release_max_level_debug`\r
//! * `release_max_level_trace`\r
//!\r
//! These features control the value of the `STATIC_MAX_LEVEL` constant. The logging macros check\r
//! this value before logging a message. By default, no levels are disabled.\r
//!\r
//! Libraries should avoid using the max level features because they're global and can't be changed\r
//! once they're set.\r
//!\r
//! For example, a crate can disable trace level logs in debug builds and trace, debug, and info\r
//! level logs in release builds with the following configuration:\r
//!\r
//! ```toml\r
//! [dependencies]\r
//! log = { version = "0.4", features = ["max_level_debug", "release_max_level_warn"] }\r
//! ```\r
//! # Crate Feature Flags\r
//!\r
//! The following crate feature flags are available in addition to the filters. They are\r
//! configured in your `Cargo.toml`.\r
//!\r
//! * `std` allows use of `std` crate instead of the default `core`. Enables using `std::error` and\r
//! `set_boxed_logger` functionality.\r
//! * `serde` enables support for serialization and deserialization of `Level` and `LevelFilter`.\r
//!\r
//! ```toml\r
//! [dependencies]\r
//! log = { version = "0.4", features = ["std", "serde"] }\r
//! ```\r
//!\r
//! # Version compatibility\r
//!\r
//! The 0.3 and 0.4 versions of the `log` crate are almost entirely compatible. Log messages\r
//! made using `log` 0.3 will forward transparently to a logger implementation using `log` 0.4. Log\r
//! messages made using `log` 0.4 will forward to a logger implementation using `log` 0.3, but the\r
//! module path and file name information associated with the message will unfortunately be lost.\r
//!\r
//! [`Log`]: trait.Log.html\r
//! [level_link]: enum.Level.html\r
//! [filter_link]: enum.LevelFilter.html\r
//! [`set_logger`]: fn.set_logger.html\r
//! [`set_max_level`]: fn.set_max_level.html\r
//! [`try_set_logger_raw`]: fn.try_set_logger_raw.html\r
//! [`shutdown_logger_raw`]: fn.shutdown_logger_raw.html\r
//! [env_logger]: https://docs.rs/env_logger/*/env_logger/\r
//! [simple_logger]: https://github.com/borntyping/rust-simple_logger\r
//! [simplelog]: https://github.com/drakulix/simplelog.rs\r
//! [pretty_env_logger]: https://docs.rs/pretty_env_logger/*/pretty_env_logger/\r
//! [stderrlog]: https://docs.rs/stderrlog/*/stderrlog/\r
//! [flexi_logger]: https://docs.rs/flexi_logger/*/flexi_logger/\r
//! [syslog]: https://docs.rs/syslog/*/syslog/\r
//! [slog-stdlog]: https://docs.rs/slog-stdlog/*/slog_stdlog/\r
//! [log4rs]: https://docs.rs/log4rs/*/log4rs/\r
//! [fern]: https://docs.rs/fern/*/fern/\r
//! [systemd-journal-logger]: https://docs.rs/systemd-journal-logger/*/systemd_journal_logger/\r
//! [android_log]: https://docs.rs/android_log/*/android_log/\r
//! [win_dbg_logger]: https://docs.rs/win_dbg_logger/*/win_dbg_logger/\r
//! [console_log]: https://docs.rs/console_log/*/console_log/\r
\r
#![doc(\r
    html_logo_url = "https://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png",\r
    html_favicon_url = "https://www.rust-lang.org/favicon.ico",\r
    html_root_url = "https://docs.rs/log/0.4.17"\r
)]\r
#![warn(missing_docs)]\r
#![deny(missing_debug_implementations, unconditional_recursion)]\r
#![cfg_attr(all(not(feature = "std"), not(test)), no_std)]\r
// When compiled for the rustc compiler itself we want to make sure that this is\r
// an unstable crate\r
#![cfg_attr(rustbuild, feature(staged_api, rustc_private))]\r
#![cfg_attr(rustbuild, unstable(feature = "rustc_private", issue = "27812"))]\r
\r
#[cfg(all(not(feature = "std"), not(test)))]\r
extern crate core as std;\r
\r
#[macro_use]\r
extern crate cfg_if;\r
\r
use std::cmp;\r
#[cfg(feature = "std")]\r
use std::error;\r
use std::fmt;\r
use std::mem;\r
use std::str::FromStr;\r
\r
#[macro_use]\r
mod macros;\r
mod serde;\r
\r
#[cfg(feature = "kv_unstable")]\r
pub mod kv;\r
\r
#[cfg(has_atomics)]\r
use std::sync::atomic::{AtomicUsize, Ordering};\r
\r
#[cfg(not(has_atomics))]\r
use std::cell::Cell;\r
#[cfg(not(has_atomics))]\r
use std::sync::atomic::Ordering;\r
\r
#[cfg(not(has_atomics))]\r
struct AtomicUsize {\r
    v: Cell<usize>,\r
}\r
\r
#[cfg(not(has_atomics))]\r
impl AtomicUsize {\r
    const fn new(v: usize) -> AtomicUsize {\r
        AtomicUsize { v: Cell::new(v) }\r
    }\r
\r
    fn load(&self, _order: Ordering) -> usize {\r
        self.v.get()\r
    }\r
\r
    fn store(&self, val: usize, _order: Ordering) {\r
        self.v.set(val)\r
    }\r
\r
    #[cfg(atomic_cas)]\r
    fn compare_exchange(\r
        &self,\r
        current: usize,\r
        new: usize,\r
        _success: Ordering,\r
        _failure: Ordering,\r
    ) -> Result<usize, usize> {\r
        let prev = self.v.get();\r
        if current == prev {\r
            self.v.set(new);\r
        }\r
        Ok(prev)\r
    }\r
}\r
\r
// Any platform without atomics is unlikely to have multiple cores, so\r
// writing via Cell will not be a race condition.\r
#[cfg(not(has_atomics))]\r
unsafe impl Sync for AtomicUsize {}\r
\r
// The LOGGER static holds a pointer to the global logger. It is protected by\r
// the STATE static which determines whether LOGGER has been initialized yet.\r
static mut LOGGER: &dyn Log = &NopLogger;\r
\r
static STATE: AtomicUsize = AtomicUsize::new(0);\r
\r
// There are three different states that we care about: the logger's\r
// uninitialized, the logger's initializing (set_logger's been called but\r
// LOGGER hasn't actually been set yet), or the logger's active.\r
const UNINITIALIZED: usize = 0;\r
const INITIALIZING: usize = 1;\r
const INITIALIZED: usize = 2;\r
\r
static MAX_LOG_LEVEL_FILTER: AtomicUsize = AtomicUsize::new(0);\r
\r
static LOG_LEVEL_NAMES: [&str; 6] = ["OFF", "ERROR", "WARN", "INFO", "DEBUG", "TRACE"];\r
\r
static SET_LOGGER_ERROR: &str = "attempted to set a logger after the logging system \\r
                                 was already initialized";\r
static LEVEL_PARSE_ERROR: &str =\r
    "attempted to convert a string that doesn't match an existing log level";\r
\r
/// An enum representing the available verbosity levels of the logger.\r
///\r
/// Typical usage includes: checking if a certain `Level` is enabled with\r
/// [`log_enabled!`](macro.log_enabled.html), specifying the `Level` of\r
/// [`log!`](macro.log.html), and comparing a `Level` directly to a\r
/// [`LevelFilter`](enum.LevelFilter.html).\r
#[repr(usize)]\r
#[derive(Copy, Eq, Debug, Hash)]\r
pub enum Level {\r
    /// The "error" level.\r
    ///\r
    /// Designates very serious errors.\r
    // This way these line up with the discriminants for LevelFilter below\r
    // This works because Rust treats field-less enums the same way as C does:\r
    // https://doc.rust-lang.org/reference/items/enumerations.html#custom-discriminant-values-for-field-less-enumerations\r
    Error = 1,\r
    /// The "warn" level.\r
    ///\r
    /// Designates hazardous situations.\r
    Warn,\r
    /// The "info" level.\r
    ///\r
    /// Designates useful information.\r
    Info,\r
    /// The "debug" level.\r
    ///\r
    /// Designates lower priority information.\r
    Debug,\r
    /// The "trace" level.\r
    ///\r
    /// Designates very low priority, often extremely verbose, information.\r
    Trace,\r
}\r
\r
impl Clone for Level {\r
    #[inline]\r
    fn clone(&self) -> Level {\r
        *self\r
    }\r
}\r
\r
impl PartialEq for Level {\r
    #[inline]\r
    fn eq(&self, other: &Level) -> bool {\r
        *self as usize == *other as usize\r
    }\r
}\r
\r
impl PartialEq<LevelFilter> for Level {\r
    #[inline]\r
    fn eq(&self, other: &LevelFilter) -> bool {\r
        *self as usize == *other as usize\r
    }\r
}\r
\r
impl PartialOrd for Level {\r
    #[inline]\r
    fn partial_cmp(&self, other: &Level) -> Option<cmp::Ordering> {\r
        Some(self.cmp(other))\r
    }\r
\r
    #[inline]\r
    fn lt(&self, other: &Level) -> bool {\r
        (*self as usize) < *other as usize\r
    }\r
\r
    #[inline]\r
    fn le(&self, other: &Level) -> bool {\r
        *self as usize <= *other as usize\r
    }\r
\r
    #[inline]\r
    fn gt(&self, other: &Level) -> bool {\r
        *self as usize > *other as usize\r
    }\r
\r
    #[inline]\r
    fn ge(&self, other: &Level) -> bool {\r
        *self as usize >= *other as usize\r
    }\r
}\r
\r
impl PartialOrd<LevelFilter> for Level {\r
    #[inline]\r
    fn partial_cmp(&self, other: &LevelFilter) -> Option<cmp::Ordering> {\r
        Some((*self as usize).cmp(&(*other as usize)))\r
    }\r
\r
    #[inline]\r
    fn lt(&self, other: &LevelFilter) -> bool {\r
        (*self as usize) < *other as usize\r
    }\r
\r
    #[inline]\r
    fn le(&self, other: &LevelFilter) -> bool {\r
        *self as usize <= *other as usize\r
    }\r
\r
    #[inline]\r
    fn gt(&self, other: &LevelFilter) -> bool {\r
        *self as usize > *other as usize\r
    }\r
\r
    #[inline]\r
    fn ge(&self, other: &LevelFilter) -> bool {\r
        *self as usize >= *other as usize\r
    }\r
}\r
\r
impl Ord for Level {\r
    #[inline]\r
    fn cmp(&self, other: &Level) -> cmp::Ordering {\r
        (*self as usize).cmp(&(*other as usize))\r
    }\r
}\r
\r
fn ok_or<T, E>(t: Option<T>, e: E) -> Result<T, E> {\r
    match t {\r
        Some(t) => Ok(t),\r
        None => Err(e),\r
    }\r
}\r
\r
// Reimplemented here because std::ascii is not available in libcore\r
fn eq_ignore_ascii_case(a: &str, b: &str) -> bool {\r
    fn to_ascii_uppercase(c: u8) -> u8 {\r
        if c >= b'a' && c <= b'z' {\r
            c - b'a' + b'A'\r
        } else {\r
            c\r
        }\r
    }\r
\r
    if a.len() == b.len() {\r
        a.bytes()\r
            .zip(b.bytes())\r
            .all(|(a, b)| to_ascii_uppercase(a) == to_ascii_uppercase(b))\r
    } else {\r
        false\r
    }\r
}\r
\r
impl FromStr for Level {\r
    type Err = ParseLevelError;\r
    fn from_str(level: &str) -> Result<Level, Self::Err> {\r
        ok_or(\r
            LOG_LEVEL_NAMES\r
                .iter()\r
                .position(|&name| eq_ignore_ascii_case(name, level))\r
                .into_iter()\r
                .filter(|&idx| idx != 0)\r
                .map(|idx| Level::from_usize(idx).unwrap())\r
                .next(),\r
            ParseLevelError(()),\r
        )\r
    }\r
}\r
\r
impl fmt::Display for Level {\r
    fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {\r
        fmt.pad(self.as_str())\r
    }\r
}\r
\r
impl Level {\r
    fn from_usize(u: usize) -> Option<Level> {\r
        match u {\r
            1 => Some(Level::Error),\r
            2 => Some(Level::Warn),\r
            3 => Some(Level::Info),\r
            4 => Some(Level::Debug),\r
            5 => Some(Level::Trace),\r
            _ => None,\r
        }\r
    }\r
\r
    /// Returns the most verbose logging level.\r
    #[inline]\r
    pub fn max() -> Level {\r
        Level::Trace\r
    }\r
\r
    /// Converts the `Level` to the equivalent `LevelFilter`.\r
    #[inline]\r
    pub fn to_level_filter(&self) -> LevelFilter {\r
        LevelFilter::from_usize(*self as usize).unwrap()\r
    }\r
\r
    /// Returns the string representation of the `Level`.\r
    ///\r
    /// This returns the same string as the `fmt::Display` implementation.\r
    pub fn as_str(&self) -> &'static str {\r
        LOG_LEVEL_NAMES[*self as usize]\r
    }\r
\r
    /// Iterate through all supported logging levels.\r
    ///\r
    /// The order of iteration is from more severe to less severe log messages.\r
    ///\r
    /// # Examples\r
    ///\r
    /// ```\r
    /// use log::Level;\r
    ///\r
    /// let mut levels = Level::iter();\r
    ///\r
    /// assert_eq!(Some(Level::Error), levels.next());\r
    /// assert_eq!(Some(Level::Trace), levels.last());\r
    /// ```\r
    pub fn iter() -> impl Iterator<Item = Self> {\r
        (1..6).map(|i| Self::from_usize(i).unwrap())\r
    }\r
}\r
\r
/// An enum representing the available verbosity level filters of the logger.\r
///\r
/// A `LevelFilter` may be compared directly to a [`Level`]. Use this type\r
/// to get and set the maximum log level with [`max_level()`] and [`set_max_level`].\r
///\r
/// [`Level`]: enum.Level.html\r
/// [`max_level()`]: fn.max_level.html\r
/// [`set_max_level`]: fn.set_max_level.html\r
#[repr(usize)]\r
#[derive(Copy, Eq, Debug, Hash)]\r
pub enum LevelFilter {\r
    /// A level lower than all log levels.\r
    Off,\r
    /// Corresponds to the `Error` log level.\r
    Error,\r
    /// Corresponds to the `Warn` log level.\r
    Warn,\r
    /// Corresponds to the `Info` log level.\r
    Info,\r
    /// Corresponds to the `Debug` log level.\r
    Debug,\r
    /// Corresponds to the `Trace` log level.\r
    Trace,\r
}\r
\r
// Deriving generates terrible impls of these traits\r
\r
impl Clone for LevelFilter {\r
    #[inline]\r
    fn clone(&self) -> LevelFilter {\r
        *self\r
    }\r
}\r
\r
impl PartialEq for LevelFilter {\r
    #[inline]\r
    fn eq(&self, other: &LevelFilter) -> bool {\r
        *self as usize == *other as usize\r
    }\r
}\r
\r
impl PartialEq<Level> for LevelFilter {\r
    #[inline]\r
    fn eq(&self, other: &Level) -> bool {\r
        other.eq(self)\r
    }\r
}\r
\r
impl PartialOrd for LevelFilter {\r
    #[inline]\r
    fn partial_cmp(&self, other: &LevelFilter) -> Option<cmp::Ordering> {\r
        Some(self.cmp(other))\r
    }\r
\r
    #[inline]\r
    fn lt(&self, other: &LevelFilter) -> bool {\r
        (*self as usize) < *other as usize\r
    }\r
\r
    #[inline]\r
    fn le(&self, other: &LevelFilter) -> bool {\r
        *self as usize <= *other as usize\r
    }\r
\r
    #[inline]\r
    fn gt(&self, other: &LevelFilter) -> bool {\r
        *self as usize > *other as usize\r
    }\r
\r
    #[inline]\r
    fn ge(&self, other: &LevelFilter) -> bool {\r
        *self as usize >= *other as usize\r
    }\r
}\r
\r
impl PartialOrd<Level> for LevelFilter {\r
    #[inline]\r
    fn partial_cmp(&self, other: &Level) -> Option<cmp::Ordering> {\r
        Some((*self as usize).cmp(&(*other as usize)))\r
    }\r
\r
    #[inline]\r
    fn lt(&self, other: &Level) -> bool {\r
        (*self as usize) < *other as usize\r
    }\r
\r
    #[inline]\r
    fn le(&self, other: &Level) -> bool {\r
        *self as usize <= *other as usize\r
    }\r
\r
    #[inline]\r
    fn gt(&self, other: &Level) -> bool {\r
        *self as usize > *other as usize\r
    }\r
\r
    #[inline]\r
    fn ge(&self, other: &Level) -> bool {\r
        *self as usize >= *other as usize\r
    }\r
}\r
\r
impl Ord for LevelFilter {\r
    #[inline]\r
    fn cmp(&self, other: &LevelFilter) -> cmp::Ordering {\r
        (*self as usize).cmp(&(*other as usize))\r
    }\r
}\r
\r
impl FromStr for LevelFilter {\r
    type Err = ParseLevelError;\r
    fn from_str(level: &str) -> Result<LevelFilter, Self::Err> {\r
        ok_or(\r
            LOG_LEVEL_NAMES\r
                .iter()\r
                .position(|&name| eq_ignore_ascii_case(name, level))\r
                .map(|p| LevelFilter::from_usize(p).unwrap()),\r
            ParseLevelError(()),\r
        )\r
    }\r
}\r
\r
impl fmt::Display for LevelFilter {\r
    fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {\r
        fmt.pad(self.as_str())\r
    }\r
}\r
\r
impl LevelFilter {\r
    fn from_usize(u: usize) -> Option<LevelFilter> {\r
        match u {\r
            0 => Some(LevelFilter::Off),\r
            1 => Some(LevelFilter::Error),\r
            2 => Some(LevelFilter::Warn),\r
            3 => Some(LevelFilter::Info),\r
            4 => Some(LevelFilter::Debug),\r
            5 => Some(LevelFilter::Trace),\r
            _ => None,\r
        }\r
    }\r
\r
    /// Returns the most verbose logging level filter.\r
    #[inline]\r
    pub fn max() -> LevelFilter {\r
        LevelFilter::Trace\r
    }\r
\r
    /// Converts `self` to the equivalent `Level`.\r
    ///\r
    /// Returns `None` if `self` is `LevelFilter::Off`.\r
    #[inline]\r
    pub fn to_level(&self) -> Option<Level> {\r
        Level::from_usize(*self as usize)\r
    }\r
\r
    /// Returns the string representation of the `LevelFilter`.\r
    ///\r
    /// This returns the same string as the `fmt::Display` implementation.\r
    pub fn as_str(&self) -> &'static str {\r
        LOG_LEVEL_NAMES[*self as usize]\r
    }\r
\r
    /// Iterate through all supported filtering levels.\r
    ///\r
    /// The order of iteration is from less to more verbose filtering.\r
    ///\r
    /// # Examples\r
    ///\r
    /// ```\r
    /// use log::LevelFilter;\r
    ///\r
    /// let mut levels = LevelFilter::iter();\r
    ///\r
    /// assert_eq!(Some(LevelFilter::Off), levels.next());\r
    /// assert_eq!(Some(LevelFilter::Trace), levels.last());\r
    /// ```\r
    pub fn iter() -> impl Iterator<Item = Self> {\r
        (0..6).map(|i| Self::from_usize(i).unwrap())\r
    }\r
}\r
\r
#[derive(Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Debug)]\r
enum MaybeStaticStr<'a> {\r
    Static(&'static str),\r
    Borrowed(&'a str),\r
}\r
\r
impl<'a> MaybeStaticStr<'a> {\r
    #[inline]\r
    fn get(&self) -> &'a str {\r
        match *self {\r
            MaybeStaticStr::Static(s) => s,\r
            MaybeStaticStr::Borrowed(s) => s,\r
        }\r
    }\r
}\r
\r
/// The "payload" of a log message.\r
///\r
/// # Use\r
///\r
/// `Record` structures are passed as parameters to the [`log`][method.log]\r
/// method of the [`Log`] trait. Logger implementors manipulate these\r
/// structures in order to display log messages. `Record`s are automatically\r
/// created by the [`log!`] macro and so are not seen by log users.\r
///\r
/// Note that the [`level()`] and [`target()`] accessors are equivalent to\r
/// `self.metadata().level()` and `self.metadata().target()` respectively.\r
/// These methods are provided as a convenience for users of this structure.\r
///\r
/// # Example\r
///\r
/// The following example shows a simple logger that displays the level,\r
/// module path, and message of any `Record` that is passed to it.\r
///\r
/// ```edition2018\r
/// struct SimpleLogger;\r
///\r
/// impl log::Log for SimpleLogger {\r
///    fn enabled(&self, metadata: &log::Metadata) -> bool {\r
///        true\r
///    }\r
///\r
///    fn log(&self, record: &log::Record) {\r
///        if !self.enabled(record.metadata()) {\r
///            return;\r
///        }\r
///\r
///        println!("{}:{} -- {}",\r
///                 record.level(),\r
///                 record.target(),\r
///                 record.args());\r
///    }\r
///    fn flush(&self) {}\r
/// }\r
/// ```\r
///\r
/// [method.log]: trait.Log.html#tymethod.log\r
/// [`Log`]: trait.Log.html\r
/// [`log!`]: macro.log.html\r
/// [`level()`]: struct.Record.html#method.level\r
/// [`target()`]: struct.Record.html#method.target\r
#[derive(Clone, Debug)]\r
pub struct Record<'a> {\r
    metadata: Metadata<'a>,\r
    args: fmt::Arguments<'a>,\r
    module_path: Option<MaybeStaticStr<'a>>,\r
    file: Option<MaybeStaticStr<'a>>,\r
    line: Option<u32>,\r
    #[cfg(feature = "kv_unstable")]\r
    key_values: KeyValues<'a>,\r
}\r
\r
// This wrapper type is only needed so we can\r
// `#[derive(Debug)]` on `Record`. It also\r
// provides a useful `Debug` implementation for\r
// the underlying `Source`.\r
#[cfg(feature = "kv_unstable")]\r
#[derive(Clone)]\r
struct KeyValues<'a>(&'a dyn kv::Source);\r
\r
#[cfg(feature = "kv_unstable")]\r
impl<'a> fmt::Debug for KeyValues<'a> {\r
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {\r
        let mut visitor = f.debug_map();\r
        self.0.visit(&mut visitor).map_err(|_| fmt::Error)?;\r
        visitor.finish()\r
    }\r
}\r
\r
impl<'a> Record<'a> {\r
    /// Returns a new builder.\r
    #[inline]\r
    pub fn builder() -> RecordBuilder<'a> {\r
        RecordBuilder::new()\r
    }\r
\r
    /// The message body.\r
    #[inline]\r
    pub fn args(&self) -> &fmt::Arguments<'a> {\r
        &self.args\r
    }\r
\r
    /// Metadata about the log directive.\r
    #[inline]\r
    pub fn metadata(&self) -> &Metadata<'a> {\r
        &self.metadata\r
    }\r
\r
    /// The verbosity level of the message.\r
    #[inline]\r
    pub fn level(&self) -> Level {\r
        self.metadata.level()\r
    }\r
\r
    /// The name of the target of the directive.\r
    #[inline]\r
    pub fn target(&self) -> &'a str {\r
        self.metadata.target()\r
    }\r
\r
    /// The module path of the message.\r
    #[inline]\r
    pub fn module_path(&self) -> Option<&'a str> {\r
        self.module_path.map(|s| s.get())\r
    }\r
\r
    /// The module path of the message, if it is a `'static` string.\r
    #[inline]\r
    pub fn module_path_static(&self) -> Option<&'static str> {\r
        match self.module_path {\r
            Some(MaybeStaticStr::Static(s)) => Some(s),\r
            _ => None,\r
        }\r
    }\r
\r
    /// The source file containing the message.\r
    #[inline]\r
    pub fn file(&self) -> Option<&'a str> {\r
        self.file.map(|s| s.get())\r
    }\r
\r
    /// The module path of the message, if it is a `'static` string.\r
    #[inline]\r
    pub fn file_static(&self) -> Option<&'static str> {\r
        match self.file {\r
            Some(MaybeStaticStr::Static(s)) => Some(s),\r
            _ => None,\r
        }\r
    }\r
\r
    /// The line containing the message.\r
    #[inline]\r
    pub fn line(&self) -> Option<u32> {\r
        self.line\r
    }\r
\r
    /// The structured key-value pairs associated with the message.\r
    #[cfg(feature = "kv_unstable")]\r
    #[inline]\r
    pub fn key_values(&self) -> &dyn kv::Source {\r
        self.key_values.0\r
    }\r
\r
    /// Create a new [`RecordBuilder`](struct.RecordBuilder.html) based on this record.\r
    #[cfg(feature = "kv_unstable")]\r
    #[inline]\r
    pub fn to_builder(&self) -> RecordBuilder {\r
        RecordBuilder {\r
            record: Record {\r
                metadata: Metadata {\r
                    level: self.metadata.level,\r
                    target: self.metadata.target,\r
                },\r
                args: self.args,\r
                module_path: self.module_path,\r
                file: self.file,\r
                line: self.line,\r
                key_values: self.key_values.clone(),\r
            },\r
        }\r
    }\r
}\r
\r
/// Builder for [`Record`](struct.Record.html).\r
///\r
/// Typically should only be used by log library creators or for testing and "shim loggers".\r
/// The `RecordBuilder` can set the different parameters of `Record` object, and returns\r
/// the created object when `build` is called.\r
///\r
/// # Examples\r
///\r
/// ```edition2018\r
/// use log::{Level, Record};\r
///\r
/// let record = Record::builder()\r
///                 .args(format_args!("Error!"))\r
///                 .level(Level::Error)\r
///                 .target("myApp")\r
///                 .file(Some("server.rs"))\r
///                 .line(Some(144))\r
///                 .module_path(Some("server"))\r
///                 .build();\r
/// ```\r
///\r
/// Alternatively, use [`MetadataBuilder`](struct.MetadataBuilder.html):\r
///\r
/// ```edition2018\r
/// use log::{Record, Level, MetadataBuilder};\r
///\r
/// let error_metadata = MetadataBuilder::new()\r
///                         .target("myApp")\r
///                         .level(Level::Error)\r
///                         .build();\r
///\r
/// let record = Record::builder()\r
///                 .metadata(error_metadata)\r
///                 .args(format_args!("Error!"))\r
///                 .line(Some(433))\r
///                 .file(Some("app.rs"))\r
///                 .module_path(Some("server"))\r
///                 .build();\r
/// ```\r
#[derive(Debug)]\r
pub struct RecordBuilder<'a> {\r
    record: Record<'a>,\r
}\r
\r
impl<'a> RecordBuilder<'a> {\r
    /// Construct new `RecordBuilder`.\r
    ///\r
    /// The default options are:\r
    ///\r
    /// - `args`: [`format_args!("")`]\r
    /// - `metadata`: [`Metadata::builder().build()`]\r
    /// - `module_path`: `None`\r
    /// - `file`: `None`\r
    /// - `line`: `None`\r
    ///\r
    /// [`format_args!("")`]: https://doc.rust-lang.org/std/macro.format_args.html\r
    /// [`Metadata::builder().build()`]: struct.MetadataBuilder.html#method.build\r
    #[inline]\r
    pub fn new() -> RecordBuilder<'a> {\r
        RecordBuilder {\r
            record: Record {\r
                args: format_args!(""),\r
                metadata: Metadata::builder().build(),\r
                module_path: None,\r
                file: None,\r
                line: None,\r
                #[cfg(feature = "kv_unstable")]\r
                key_values: KeyValues(&Option::None::<(kv::Key, kv::Value)>),\r
            },\r
        }\r
    }\r
\r
    /// Set [`args`](struct.Record.html#method.args).\r
    #[inline]\r
    pub fn args(&mut self, args: fmt::Arguments<'a>) -> &mut RecordBuilder<'a> {\r
        self.record.args = args;\r
        self\r
    }\r
\r
    /// Set [`metadata`](struct.Record.html#method.metadata). Construct a `Metadata` object with [`MetadataBuilder`](struct.MetadataBuilder.html).\r
    #[inline]\r
    pub fn metadata(&mut self, metadata: Metadata<'a>) -> &mut RecordBuilder<'a> {\r
        self.record.metadata = metadata;\r
        self\r
    }\r
\r
    /// Set [`Metadata::level`](struct.Metadata.html#method.level).\r
    #[inline]\r
    pub fn level(&mut self, level: Level) -> &mut RecordBuilder<'a> {\r
        self.record.metadata.level = level;\r
        self\r
    }\r
\r
    /// Set [`Metadata::target`](struct.Metadata.html#method.target)\r
    #[inline]\r
    pub fn target(&mut self, target: &'a str) -> &mut RecordBuilder<'a> {\r
        self.record.metadata.target = target;\r
        self\r
    }\r
\r
    /// Set [`module_path`](struct.Record.html#method.module_path)\r
    #[inline]\r
    pub fn module_path(&mut self, path: Option<&'a str>) -> &mut RecordBuilder<'a> {\r
        self.record.module_path = path.map(MaybeStaticStr::Borrowed);\r
        self\r
    }\r
\r
    /// Set [`module_path`](struct.Record.html#method.module_path) to a `'static` string\r
    #[inline]\r
    pub fn module_path_static(&mut self, path: Option<&'static str>) -> &mut RecordBuilder<'a> {\r
        self.record.module_path = path.map(MaybeStaticStr::Static);\r
        self\r
    }\r
\r
    /// Set [`file`](struct.Record.html#method.file)\r
    #[inline]\r
    pub fn file(&mut self, file: Option<&'a str>) -> &mut RecordBuilder<'a> {\r
        self.record.file = file.map(MaybeStaticStr::Borrowed);\r
        self\r
    }\r
\r
    /// Set [`file`](struct.Record.html#method.file) to a `'static` string.\r
    #[inline]\r
    pub fn file_static(&mut self, file: Option<&'static str>) -> &mut RecordBuilder<'a> {\r
        self.record.file = file.map(MaybeStaticStr::Static);\r
        self\r
    }\r
\r
    /// Set [`line`](struct.Record.html#method.line)\r
    #[inline]\r
    pub fn line(&mut self, line: Option<u32>) -> &mut RecordBuilder<'a> {\r
        self.record.line = line;\r
        self\r
    }\r
\r
    /// Set [`key_values`](struct.Record.html#method.key_values)\r
    #[cfg(feature = "kv_unstable")]\r
    #[inline]\r
    pub fn key_values(&mut self, kvs: &'a dyn kv::Source) -> &mut RecordBuilder<'a> {\r
        self.record.key_values = KeyValues(kvs);\r
        self\r
    }\r
\r
    /// Invoke the builder and return a `Record`\r
    #[inline]\r
    pub fn build(&self) -> Record<'a> {\r
        self.record.clone()\r
    }\r
}\r
\r
/// Metadata about a log message.\r
///\r
/// # Use\r
///\r
/// `Metadata` structs are created when users of the library use\r
/// logging macros.\r
///\r
/// They are consumed by implementations of the `Log` trait in the\r
/// `enabled` method.\r
///\r
/// `Record`s use `Metadata` to determine the log message's severity\r
/// and target.\r
///\r
/// Users should use the `log_enabled!` macro in their code to avoid\r
/// constructing expensive log messages.\r
///\r
/// # Examples\r
///\r
/// ```edition2018\r
/// use log::{Record, Level, Metadata};\r
///\r
/// struct MyLogger;\r
///\r
/// impl log::Log for MyLogger {\r
///     fn enabled(&self, metadata: &Metadata) -> bool {\r
///         metadata.level() <= Level::Info\r
///     }\r
///\r
///     fn log(&self, record: &Record) {\r
///         if self.enabled(record.metadata()) {\r
///             println!("{} - {}", record.level(), record.args());\r
///         }\r
///     }\r
///     fn flush(&self) {}\r
/// }\r
///\r
/// # fn main(){}\r
/// ```\r
#[derive(Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Debug)]\r
pub struct Metadata<'a> {\r
    level: Level,\r
    target: &'a str,\r
}\r
\r
impl<'a> Metadata<'a> {\r
    /// Returns a new builder.\r
    #[inline]\r
    pub fn builder() -> MetadataBuilder<'a> {\r
        MetadataBuilder::new()\r
    }\r
\r
    /// The verbosity level of the message.\r
    #[inline]\r
    pub fn level(&self) -> Level {\r
        self.level\r
    }\r
\r
    /// The name of the target of the directive.\r
    #[inline]\r
    pub fn target(&self) -> &'a str {\r
        self.target\r
    }\r
}\r
\r
/// Builder for [`Metadata`](struct.Metadata.html).\r
///\r
/// Typically should only be used by log library creators or for testing and "shim loggers".\r
/// The `MetadataBuilder` can set the different parameters of a `Metadata` object, and returns\r
/// the created object when `build` is called.\r
///\r
/// # Example\r
///\r
/// ```edition2018\r
/// let target = "myApp";\r
/// use log::{Level, MetadataBuilder};\r
/// let metadata = MetadataBuilder::new()\r
///                     .level(Level::Debug)\r
///                     .target(target)\r
///                     .build();\r
/// ```\r
#[derive(Eq, PartialEq, Ord, PartialOrd, Hash, Debug)]\r
pub struct MetadataBuilder<'a> {\r
    metadata: Metadata<'a>,\r
}\r
\r
impl<'a> MetadataBuilder<'a> {\r
    /// Construct a new `MetadataBuilder`.\r
    ///\r
    /// The default options are:\r
    ///\r
    /// - `level`: `Level::Info`\r
    /// - `target`: `""`\r
    #[inline]\r
    pub fn new() -> MetadataBuilder<'a> {\r
        MetadataBuilder {\r
            metadata: Metadata {\r
                level: Level::Info,\r
                target: "",\r
            },\r
        }\r
    }\r
\r
    /// Setter for [`level`](struct.Metadata.html#method.level).\r
    #[inline]\r
    pub fn level(&mut self, arg: Level) -> &mut MetadataBuilder<'a> {\r
        self.metadata.level = arg;\r
        self\r
    }\r
\r
    /// Setter for [`target`](struct.Metadata.html#method.target).\r
    #[inline]\r
    pub fn target(&mut self, target: &'a str) -> &mut MetadataBuilder<'a> {\r
        self.metadata.target = target;\r
        self\r
    }\r
\r
    /// Returns a `Metadata` object.\r
    #[inline]\r
    pub fn build(&self) -> Metadata<'a> {\r
        self.metadata.clone()\r
    }\r
}\r
\r
/// A trait encapsulating the operations required of a logger.\r
pub trait Log: Sync + Send {\r
    /// Determines if a log message with the specified metadata would be\r
    /// logged.\r
    ///\r
    /// This is used by the `log_enabled!` macro to allow callers to avoid\r
    /// expensive computation of log message arguments if the message would be\r
    /// discarded anyway.\r
    ///\r
    /// # For implementors\r
    ///\r
    /// This method isn't called automatically by the `log!` macros.\r
    /// It's up to an implementation of the `Log` trait to call `enabled` in its own\r
    /// `log` method implementation to guarantee that filtering is applied.\r
    fn enabled(&self, metadata: &Metadata) -> bool;\r
\r
    /// Logs the `Record`.\r
    ///\r
    /// # For implementors\r
    ///\r
    /// Note that `enabled` is *not* necessarily called before this method.\r
    /// Implementations of `log` should perform all necessary filtering\r
    /// internally.\r
    fn log(&self, record: &Record);\r
\r
    /// Flushes any buffered records.\r
    fn flush(&self);\r
}\r
\r
// Just used as a dummy initial value for LOGGER\r
struct NopLogger;\r
\r
impl Log for NopLogger {\r
    fn enabled(&self, _: &Metadata) -> bool {\r
        false\r
    }\r
\r
    fn log(&self, _: &Record) {}\r
    fn flush(&self) {}\r
}\r
\r
impl<T> Log for &'_ T\r
where\r
    T: ?Sized + Log,\r
{\r
    fn enabled(&self, metadata: &Metadata) -> bool {\r
        (**self).enabled(metadata)\r
    }\r
\r
    fn log(&self, record: &Record) {\r
        (**self).log(record)\r
    }\r
    fn flush(&self) {\r
        (**self).flush()\r
    }\r
}\r
\r
#[cfg(feature = "std")]\r
impl<T> Log for std::boxed::Box<T>\r
where\r
    T: ?Sized + Log,\r
{\r
    fn enabled(&self, metadata: &Metadata) -> bool {\r
        self.as_ref().enabled(metadata)\r
    }\r
\r
    fn log(&self, record: &Record) {\r
        self.as_ref().log(record)\r
    }\r
    fn flush(&self) {\r
        self.as_ref().flush()\r
    }\r
}\r
\r
#[cfg(feature = "std")]\r
impl<T> Log for std::sync::Arc<T>\r
where\r
    T: ?Sized + Log,\r
{\r
    fn enabled(&self, metadata: &Metadata) -> bool {\r
        self.as_ref().enabled(metadata)\r
    }\r
\r
    fn log(&self, record: &Record) {\r
        self.as_ref().log(record)\r
    }\r
    fn flush(&self) {\r
        self.as_ref().flush()\r
    }\r
}\r
\r
/// Sets the global maximum log level.\r
///\r
/// Generally, this should only be called by the active logging implementation.\r
///\r
/// Note that `Trace` is the maximum level, because it provides the maximum amount of detail in the emitted logs.\r
#[inline]\r
pub fn set_max_level(level: LevelFilter) {\r
    MAX_LOG_LEVEL_FILTER.store(level as usize, Ordering::Relaxed)\r
}\r
\r
/// Returns the current maximum log level.\r
///\r
/// The [`log!`], [`error!`], [`warn!`], [`info!`], [`debug!`], and [`trace!`] macros check\r
/// this value and discard any message logged at a higher level. The maximum\r
/// log level is set by the [`set_max_level`] function.\r
///\r
/// [`log!`]: macro.log.html\r
/// [`error!`]: macro.error.html\r
/// [`warn!`]: macro.warn.html\r
/// [`info!`]: macro.info.html\r
/// [`debug!`]: macro.debug.html\r
/// [`trace!`]: macro.trace.html\r
/// [`set_max_level`]: fn.set_max_level.html\r
#[inline(always)]\r
pub fn max_level() -> LevelFilter {\r
    // Since `LevelFilter` is `repr(usize)`,\r
    // this transmute is sound if and only if `MAX_LOG_LEVEL_FILTER`\r
    // is set to a usize that is a valid discriminant for `LevelFilter`.\r
    // Since `MAX_LOG_LEVEL_FILTER` is private, the only time it's set\r
    // is by `set_max_level` above, i.e. by casting a `LevelFilter` to `usize`.\r
    // So any usize stored in `MAX_LOG_LEVEL_FILTER` is a valid discriminant.\r
    unsafe { mem::transmute(MAX_LOG_LEVEL_FILTER.load(Ordering::Relaxed)) }\r
}\r
\r
/// Sets the global logger to a `Box<Log>`.\r
///\r
/// This is a simple convenience wrapper over `set_logger`, which takes a\r
/// `Box<Log>` rather than a `&'static Log`. See the documentation for\r
/// [`set_logger`] for more details.\r
///\r
/// Requires the `std` feature.\r
///\r
/// # Errors\r
///\r
/// An error is returned if a logger has already been set.\r
///\r
/// [`set_logger`]: fn.set_logger.html\r
#[cfg(all(feature = "std", atomic_cas))]\r
pub fn set_boxed_logger(logger: Box<dyn Log>) -> Result<(), SetLoggerError> {\r
    set_logger_inner(|| Box::leak(logger))\r
}\r
\r
/// Sets the global logger to a `&'static Log`.\r
///\r
/// This function may only be called once in the lifetime of a program. Any log\r
/// events that occur before the call to `set_logger` completes will be ignored.\r
///\r
/// This function does not typically need to be called manually. Logger\r
/// implementations should provide an initialization method that installs the\r
/// logger internally.\r
///\r
/// # Availability\r
///\r
/// This method is available even when the `std` feature is disabled. However,\r
/// it is currently unavailable on `thumbv6` targets, which lack support for\r
/// some atomic operations which are used by this function. Even on those\r
/// targets, [`set_logger_racy`] will be available.\r
///\r
/// # Errors\r
///\r
/// An error is returned if a logger has already been set.\r
///\r
/// # Examples\r
///\r
/// ```edition2018\r
/// use log::{error, info, warn, Record, Level, Metadata, LevelFilter};\r
///\r
/// static MY_LOGGER: MyLogger = MyLogger;\r
///\r
/// struct MyLogger;\r
///\r
/// impl log::Log for MyLogger {\r
///     fn enabled(&self, metadata: &Metadata) -> bool {\r
///         metadata.level() <= Level::Info\r
///     }\r
///\r
///     fn log(&self, record: &Record) {\r
///         if self.enabled(record.metadata()) {\r
///             println!("{} - {}", record.level(), record.args());\r
///         }\r
///     }\r
///     fn flush(&self) {}\r
/// }\r
///\r
/// # fn main(){\r
/// log::set_logger(&MY_LOGGER).unwrap();\r
/// log::set_max_level(LevelFilter::Info);\r
///\r
/// info!("hello log");\r
/// warn!("warning");\r
/// error!("oops");\r
/// # }\r
/// ```\r
///\r
/// [`set_logger_racy`]: fn.set_logger_racy.html\r
#[cfg(atomic_cas)]\r
pub fn set_logger(logger: &'static dyn Log) -> Result<(), SetLoggerError> {\r
    set_logger_inner(|| logger)\r
}\r
\r
#[cfg(atomic_cas)]\r
fn set_logger_inner<F>(make_logger: F) -> Result<(), SetLoggerError>\r
where\r
    F: FnOnce() -> &'static dyn Log,\r
{\r
    let old_state = match STATE.compare_exchange(\r
        UNINITIALIZED,\r
        INITIALIZING,\r
        Ordering::SeqCst,\r
        Ordering::SeqCst,\r
    ) {\r
        Ok(s) | Err(s) => s,\r
    };\r
    match old_state {\r
        UNINITIALIZED => {\r
            unsafe {\r
                LOGGER = make_logger();\r
            }\r
            STATE.store(INITIALIZED, Ordering::SeqCst);\r
            Ok(())\r
        }\r
        INITIALIZING => {\r
            while STATE.load(Ordering::SeqCst) == INITIALIZING {\r
                // TODO: replace with `hint::spin_loop` once MSRV is 1.49.0.\r
                #[allow(deprecated)]\r
                std::sync::atomic::spin_loop_hint();\r
            }\r
            Err(SetLoggerError(()))\r
        }\r
        _ => Err(SetLoggerError(())),\r
    }\r
}\r
\r
/// A thread-unsafe version of [`set_logger`].\r
///\r
/// This function is available on all platforms, even those that do not have\r
/// support for atomics that is needed by [`set_logger`].\r
///\r
/// In almost all cases, [`set_logger`] should be preferred.\r
///\r
/// # Safety\r
///\r
/// This function is only safe to call when no other logger initialization\r
/// function is called while this function still executes.\r
///\r
/// This can be upheld by (for example) making sure that **there are no other\r
/// threads**, and (on embedded) that **interrupts are disabled**.\r
///\r
/// It is safe to use other logging functions while this function runs\r
/// (including all logging macros).\r
///\r
/// [`set_logger`]: fn.set_logger.html\r
pub unsafe fn set_logger_racy(logger: &'static dyn Log) -> Result<(), SetLoggerError> {\r
    match STATE.load(Ordering::SeqCst) {\r
        UNINITIALIZED => {\r
            LOGGER = logger;\r
            STATE.store(INITIALIZED, Ordering::SeqCst);\r
            Ok(())\r
        }\r
        INITIALIZING => {\r
            // This is just plain UB, since we were racing another initialization function\r
            unreachable!("set_logger_racy must not be used with other initialization functions")\r
        }\r
        _ => Err(SetLoggerError(())),\r
    }\r
}\r
\r
/// The type returned by [`set_logger`] if [`set_logger`] has already been called.\r
///\r
/// [`set_logger`]: fn.set_logger.html\r
#[allow(missing_copy_implementations)]\r
#[derive(Debug)]\r
pub struct SetLoggerError(());\r
\r
impl fmt::Display for SetLoggerError {\r
    fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {\r
        fmt.write_str(SET_LOGGER_ERROR)\r
    }\r
}\r
\r
// The Error trait is not available in libcore\r
#[cfg(feature = "std")]\r
impl error::Error for SetLoggerError {}\r
\r
/// The type returned by [`from_str`] when the string doesn't match any of the log levels.\r
///\r
/// [`from_str`]: https://doc.rust-lang.org/std/str/trait.FromStr.html#tymethod.from_str\r
#[allow(missing_copy_implementations)]\r
#[derive(Debug, PartialEq)]\r
pub struct ParseLevelError(());\r
\r
impl fmt::Display for ParseLevelError {\r
    fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {\r
        fmt.write_str(LEVEL_PARSE_ERROR)\r
    }\r
}\r
\r
// The Error trait is not available in libcore\r
#[cfg(feature = "std")]\r
impl error::Error for ParseLevelError {}\r
\r
/// Returns a reference to the logger.\r
///\r
/// If a logger has not been set, a no-op implementation is returned.\r
pub fn logger() -> &'static dyn Log {\r
    if STATE.load(Ordering::SeqCst) != INITIALIZED {\r
        static NOP: NopLogger = NopLogger;\r
        &NOP\r
    } else {\r
        unsafe { LOGGER }\r
    }\r
}\r
\r
// WARNING: this is not part of the crate's public API and is subject to change at any time\r
#[doc(hidden)]\r
#[cfg(not(feature = "kv_unstable"))]\r
pub fn __private_api_log(\r
    args: fmt::Arguments,\r
    level: Level,\r
    &(target, module_path, file, line): &(&str, &'static str, &'static str, u32),\r
    kvs: Option<&[(&str, &str)]>,\r
) {\r
    if kvs.is_some() {\r
        panic!(\r
            "key-value support is experimental and must be enabled using the `kv_unstable` feature"\r
        )\r
    }\r
\r
    logger().log(\r
        &Record::builder()\r
            .args(args)\r
            .level(level)\r
            .target(target)\r
            .module_path_static(Some(module_path))\r
            .file_static(Some(file))\r
            .line(Some(line))\r
            .build(),\r
    );\r
}\r
\r
// WARNING: this is not part of the crate's public API and is subject to change at any time\r
#[doc(hidden)]\r
#[cfg(feature = "kv_unstable")]\r
pub fn __private_api_log(\r
    args: fmt::Arguments,\r
    level: Level,\r
    &(target, module_path, file, line): &(&str, &'static str, &'static str, u32),\r
    kvs: Option<&[(&str, &dyn kv::ToValue)]>,\r
) {\r
    logger().log(\r
        &Record::builder()\r
            .args(args)\r
            .level(level)\r
            .target(target)\r
            .module_path_static(Some(module_path))\r
            .file_static(Some(file))\r
            .line(Some(line))\r
            .key_values(&kvs)\r
            .build(),\r
    );\r
}\r
\r
// WARNING: this is not part of the crate's public API and is subject to change at any time\r
#[doc(hidden)]\r
pub fn __private_api_enabled(level: Level, target: &str) -> bool {\r
    logger().enabled(&Metadata::builder().level(level).target(target).build())\r
}\r
\r
// WARNING: this is not part of the crate's public API and is subject to change at any time\r
#[doc(hidden)]\r
pub mod __private_api {\r
    pub use std::option::Option;\r
}\r
\r
/// The statically resolved maximum log level.\r
///\r
/// See the crate level documentation for information on how to configure this.\r
///\r
/// This value is checked by the log macros, but not by the `Log`ger returned by\r
/// the [`logger`] function. Code that manually calls functions on that value\r
/// should compare the level against this value.\r
///\r
/// [`logger`]: fn.logger.html\r
pub const STATIC_MAX_LEVEL: LevelFilter = MAX_LEVEL_INNER;\r
\r
cfg_if! {\r
    if #[cfg(all(not(debug_assertions), feature = "release_max_level_off"))] {\r
        const MAX_LEVEL_INNER: LevelFilter = LevelFilter::Off;\r
    } else if #[cfg(all(not(debug_assertions), feature = "release_max_level_error"))] {\r
        const MAX_LEVEL_INNER: LevelFilter = LevelFilter::Error;\r
    } else if #[cfg(all(not(debug_assertions), feature = "release_max_level_warn"))] {\r
        const MAX_LEVEL_INNER: LevelFilter = LevelFilter::Warn;\r
    } else if #[cfg(all(not(debug_assertions), feature = "release_max_level_info"))] {\r
        const MAX_LEVEL_INNER: LevelFilter = LevelFilter::Info;\r
    } else if #[cfg(all(not(debug_assertions), feature = "release_max_level_debug"))] {\r
        const MAX_LEVEL_INNER: LevelFilter = LevelFilter::Debug;\r
    } else if #[cfg(all(not(debug_assertions), feature = "release_max_level_trace"))] {\r
        const MAX_LEVEL_INNER: LevelFilter = LevelFilter::Trace;\r
    } else if #[cfg(feature = "max_level_off")] {\r
        const MAX_LEVEL_INNER: LevelFilter = LevelFilter::Off;\r
    } else if #[cfg(feature = "max_level_error")] {\r
        const MAX_LEVEL_INNER: LevelFilter = LevelFilter::Error;\r
    } else if #[cfg(feature = "max_level_warn")] {\r
        const MAX_LEVEL_INNER: LevelFilter = LevelFilter::Warn;\r
    } else if #[cfg(feature = "max_level_info")] {\r
        const MAX_LEVEL_INNER: LevelFilter = LevelFilter::Info;\r
    } else if #[cfg(feature = "max_level_debug")] {\r
        const MAX_LEVEL_INNER: LevelFilter = LevelFilter::Debug;\r
    } else {\r
        const MAX_LEVEL_INNER: LevelFilter = LevelFilter::Trace;\r
    }\r
}\r
\r
#[cfg(test)]\r
mod tests {\r
    extern crate std;\r
    use super::{Level, LevelFilter, ParseLevelError};\r
    use tests::std::string::ToString;\r
\r
    #[test]\r
    fn test_levelfilter_from_str() {\r
        let tests = [\r
            ("off", Ok(LevelFilter::Off)),\r
            ("error", Ok(LevelFilter::Error)),\r
            ("warn", Ok(LevelFilter::Warn)),\r
            ("info", Ok(LevelFilter::Info)),\r
            ("debug", Ok(LevelFilter::Debug)),\r
            ("trace", Ok(LevelFilter::Trace)),\r
            ("OFF", Ok(LevelFilter::Off)),\r
            ("ERROR", Ok(LevelFilter::Error)),\r
            ("WARN", Ok(LevelFilter::Warn)),\r
            ("INFO", Ok(LevelFilter::Info)),\r
            ("DEBUG", Ok(LevelFilter::Debug)),\r
            ("TRACE", Ok(LevelFilter::Trace)),\r
            ("asdf", Err(ParseLevelError(()))),\r
        ];\r
        for &(s, ref expected) in &tests {\r
            assert_eq!(expected, &s.parse());\r
        }\r
    }\r
\r
    #[test]\r
    fn test_level_from_str() {\r
        let tests = [\r
            ("OFF", Err(ParseLevelError(()))),\r
            ("error", Ok(Level::Error)),\r
            ("warn", Ok(Level::Warn)),\r
            ("info", Ok(Level::Info)),\r
            ("debug", Ok(Level::Debug)),\r
            ("trace", Ok(Level::Trace)),\r
            ("ERROR", Ok(Level::Error)),\r
            ("WARN", Ok(Level::Warn)),\r
            ("INFO", Ok(Level::Info)),\r
            ("DEBUG", Ok(Level::Debug)),\r
            ("TRACE", Ok(Level::Trace)),\r
            ("asdf", Err(ParseLevelError(()))),\r
        ];\r
        for &(s, ref expected) in &tests {\r
            assert_eq!(expected, &s.parse());\r
        }\r
    }\r
\r
    #[test]\r
    fn test_level_as_str() {\r
        let tests = &[\r
            (Level::Error, "ERROR"),\r
            (Level::Warn, "WARN"),\r
            (Level::Info, "INFO"),\r
            (Level::Debug, "DEBUG"),\r
            (Level::Trace, "TRACE"),\r
        ];\r
        for (input, expected) in tests {\r
            assert_eq!(*expected, input.as_str());\r
        }\r
    }\r
\r
    #[test]\r
    fn test_level_show() {\r
        assert_eq!("INFO", Level::Info.to_string());\r
        assert_eq!("ERROR", Level::Error.to_string());\r
    }\r
\r
    #[test]\r
    fn test_levelfilter_show() {\r
        assert_eq!("OFF", LevelFilter::Off.to_string());\r
        assert_eq!("ERROR", LevelFilter::Error.to_string());\r
    }\r
\r
    #[test]\r
    fn test_cross_cmp() {\r
        assert!(Level::Debug > LevelFilter::Error);\r
        assert!(LevelFilter::Warn < Level::Trace);\r
        assert!(LevelFilter::Off < Level::Error);\r
    }\r
\r
    #[test]\r
    fn test_cross_eq() {\r
        assert!(Level::Error == LevelFilter::Error);\r
        assert!(LevelFilter::Off != Level::Error);\r
        assert!(Level::Trace == LevelFilter::Trace);\r
    }\r
\r
    #[test]\r
    fn test_to_level() {\r
        assert_eq!(Some(Level::Error), LevelFilter::Error.to_level());\r
        assert_eq!(None, LevelFilter::Off.to_level());\r
        assert_eq!(Some(Level::Debug), LevelFilter::Debug.to_level());\r
    }\r
\r
    #[test]\r
    fn test_to_level_filter() {\r
        assert_eq!(LevelFilter::Error, Level::Error.to_level_filter());\r
        assert_eq!(LevelFilter::Trace, Level::Trace.to_level_filter());\r
    }\r
\r
    #[test]\r
    fn test_level_filter_as_str() {\r
        let tests = &[\r
            (LevelFilter::Off, "OFF"),\r
            (LevelFilter::Error, "ERROR"),\r
            (LevelFilter::Warn, "WARN"),\r
            (LevelFilter::Info, "INFO"),\r
            (LevelFilter::Debug, "DEBUG"),\r
            (LevelFilter::Trace, "TRACE"),\r
        ];\r
        for (input, expected) in tests {\r
            assert_eq!(*expected, input.as_str());\r
        }\r
    }\r
\r
    #[test]\r
    #[cfg(feature = "std")]\r
    fn test_error_trait() {\r
        use super::SetLoggerError;\r
        let e = SetLoggerError(());\r
        assert_eq!(\r
            &e.to_string(),\r
            "attempted to set a logger after the logging system \\r
             was already initialized"\r
        );\r
    }\r
\r
    #[test]\r
    fn test_metadata_builder() {\r
        use super::MetadataBuilder;\r
        let target = "myApp";\r
        let metadata_test = MetadataBuilder::new()\r
            .level(Level::Debug)\r
            .target(target)\r
            .build();\r
        assert_eq!(metadata_test.level(), Level::Debug);\r
        assert_eq!(metadata_test.target(), "myApp");\r
    }\r
\r
    #[test]\r
    fn test_metadata_convenience_builder() {\r
        use super::Metadata;\r
        let target = "myApp";\r
        let metadata_test = Metadata::builder()\r
            .level(Level::Debug)\r
            .target(target)\r
            .build();\r
        assert_eq!(metadata_test.level(), Level::Debug);\r
        assert_eq!(metadata_test.target(), "myApp");\r
    }\r
\r
    #[test]\r
    fn test_record_builder() {\r
        use super::{MetadataBuilder, RecordBuilder};\r
        let target = "myApp";\r
        let metadata = MetadataBuilder::new().target(target).build();\r
        let fmt_args = format_args!("hello");\r
        let record_test = RecordBuilder::new()\r
            .args(fmt_args)\r
            .metadata(metadata)\r
            .module_path(Some("foo"))\r
            .file(Some("bar"))\r
            .line(Some(30))\r
            .build();\r
        assert_eq!(record_test.metadata().target(), "myApp");\r
        assert_eq!(record_test.module_path(), Some("foo"));\r
        assert_eq!(record_test.file(), Some("bar"));\r
        assert_eq!(record_test.line(), Some(30));\r
    }\r
\r
    #[test]\r
    fn test_record_convenience_builder() {\r
        use super::{Metadata, Record};\r
        let target = "myApp";\r
        let metadata = Metadata::builder().target(target).build();\r
        let fmt_args = format_args!("hello");\r
        let record_test = Record::builder()\r
            .args(fmt_args)\r
            .metadata(metadata)\r
            .module_path(Some("foo"))\r
            .file(Some("bar"))\r
            .line(Some(30))\r
            .build();\r
        assert_eq!(record_test.target(), "myApp");\r
        assert_eq!(record_test.module_path(), Some("foo"));\r
        assert_eq!(record_test.file(), Some("bar"));\r
        assert_eq!(record_test.line(), Some(30));\r
    }\r
\r
    #[test]\r
    fn test_record_complete_builder() {\r
        use super::{Level, Record};\r
        let target = "myApp";\r
        let record_test = Record::builder()\r
            .module_path(Some("foo"))\r
            .file(Some("bar"))\r
            .line(Some(30))\r
            .target(target)\r
            .level(Level::Error)\r
            .build();\r
        assert_eq!(record_test.target(), "myApp");\r
        assert_eq!(record_test.level(), Level::Error);\r
        assert_eq!(record_test.module_path(), Some("foo"));\r
        assert_eq!(record_test.file(), Some("bar"));\r
        assert_eq!(record_test.line(), Some(30));\r
    }\r
\r
    #[test]\r
    #[cfg(feature = "kv_unstable")]\r
    fn test_record_key_values_builder() {\r
        use super::Record;\r
        use kv::{self, Visitor};\r
\r
        struct TestVisitor {\r
            seen_pairs: usize,\r
        }\r
\r
        impl<'kvs> Visitor<'kvs> for TestVisitor {\r
            fn visit_pair(\r
                &mut self,\r
                _: kv::Key<'kvs>,\r
                _: kv::Value<'kvs>,\r
            ) -> Result<(), kv::Error> {\r
                self.seen_pairs += 1;\r
                Ok(())\r
            }\r
        }\r
\r
        let kvs: &[(&str, i32)] = &[("a", 1), ("b", 2)];\r
        let record_test = Record::builder().key_values(&kvs).build();\r
\r
        let mut visitor = TestVisitor { seen_pairs: 0 };\r
\r
        record_test.key_values().visit(&mut visitor).unwrap();\r
\r
        assert_eq!(2, visitor.seen_pairs);\r
    }\r
\r
    #[test]\r
    #[cfg(feature = "kv_unstable")]\r
    fn test_record_key_values_get_coerce() {\r
        use super::Record;\r
\r
        let kvs: &[(&str, &str)] = &[("a", "1"), ("b", "2")];\r
        let record = Record::builder().key_values(&kvs).build();\r
\r
        assert_eq!(\r
            "2",\r
            record\r
                .key_values()\r
                .get("b".into())\r
                .expect("missing key")\r
                .to_borrowed_str()\r
                .expect("invalid value")\r
        );\r
    }\r
\r
    // Test that the `impl Log for Foo` blocks work\r
    // This test mostly operates on a type level, so failures will be compile errors\r
    #[test]\r
    fn test_foreign_impl() {\r
        use super::Log;\r
        #[cfg(feature = "std")]\r
        use std::sync::Arc;\r
\r
        fn assert_is_log<T: Log + ?Sized>() {}\r
\r
        assert_is_log::<&dyn Log>();\r
\r
        #[cfg(feature = "std")]\r
        assert_is_log::<Box<dyn Log>>();\r
\r
        #[cfg(feature = "std")]\r
        assert_is_log::<Arc<dyn Log>>();\r
\r
        // Assert these statements for all T: Log + ?Sized\r
        #[allow(unused)]\r
        fn forall<T: Log + ?Sized>() {\r
            #[cfg(feature = "std")]\r
            assert_is_log::<Box<T>>();\r
\r
            assert_is_log::<&T>();\r
\r
            #[cfg(feature = "std")]\r
            assert_is_log::<Arc<T>>();\r
        }\r
    }\r
}\r