Debian Codegraph @

.cargo/vendor/log/src/lib.rs

raw
1 // Copyright 2015 The Rust Project Developers. See the COPYRIGHT
2 // file at the top-level directory of this distribution and at
3 // http://rust-lang.org/COPYRIGHT.
4 //
5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
8 // option. This file may not be copied, modified, or distributed
9 // except according to those terms.
10
11 //! A lightweight logging facade.
12 //!
13 //! The `log` crate provides a single logging API that abstracts over the
14 //! actual logging implementation. Libraries can use the logging API provided
15 //! by this crate, and the consumer of those libraries can choose the logging
16 //! implementation that is most suitable for its use case.
17 //!
18 //! If no logging implementation is selected, the facade falls back to a "noop"
19 //! implementation that ignores all log messages. The overhead in this case
20 //! is very small - just an integer load, comparison and jump.
21 //!
22 //! A log request consists of a _target_, a _level_, and a _body_. A target is a
23 //! string which defaults to the module path of the location of the log request,
24 //! though that default may be overridden. Logger implementations typically use
25 //! the target to filter requests based on some user configuration.
26 //!
27 //! # Usage
28 //!
29 //! The basic use of the log crate is through the five logging macros: [`error!`],
30 //! [`warn!`], [`info!`], [`debug!`] and [`trace!`]
31 //! where `error!` represents the highest-priority log messages
32 //! and `trace!` the lowest. The log messages are filtered by configuring
33 //! the log level to exclude messages with a lower priority.
34 //! Each of these macros accept format strings similarly to [`println!`].
35 //!
36 //!
37 //! [`error!`]: ./macro.error.html
38 //! [`warn!`]: ./macro.warn.html
39 //! [`info!`]: ./macro.info.html
40 //! [`debug!`]: ./macro.debug.html
41 //! [`trace!`]: ./macro.trace.html
42 //! [`println!`]: https://doc.rust-lang.org/stable/std/macro.println.html
43 //!
44 //! ## In libraries
45 //!
46 //! Libraries should link only to the `log` crate, and use the provided
47 //! macros to log whatever information will be useful to downstream consumers.
48 //!
49 //! ### Examples
50 //!
51 //! ```
52 //! # #[derive(Debug)] pub struct Yak(String);
53 //! # impl Yak { fn shave(&mut self, _: u32) {} }
54 //! # fn find_a_razor() -> Result<u32, u32> { Ok(1) }
55 //! use log::{info, warn};
56 //!
57 //! pub fn shave_the_yak(yak: &mut Yak) {
58 //! info!(target: "yak_events", "Commencing yak shaving for {yak:?}");
59 //!
60 //! loop {
61 //! match find_a_razor() {
62 //! Ok(razor) => {
63 //! info!("Razor located: {razor}");
64 //! yak.shave(razor);
65 //! break;
66 //! }
67 //! Err(err) => {
68 //! warn!("Unable to locate a razor: {err}, retrying");
69 //! }
70 //! }
71 //! }
72 //! }
73 //! # fn main() {}
74 //! ```
75 //!
76 //! ## In executables
77 //!
78 //! Executables should choose a logging implementation and initialize it early in the
79 //! runtime of the program. Logging implementations will typically include a
80 //! function to do this. Any log messages generated before
81 //! the implementation is initialized will be ignored.
82 //!
83 //! The executable itself may use the `log` crate to log as well.
84 //!
85 //! ### Warning
86 //!
87 //! The logging system may only be initialized once.
88 //!
89 //! ## Structured logging
90 //!
91 //! If you enable the `kv` feature you can associate structured values
92 //! with your log records. If we take the example from before, we can include
93 //! some additional context besides what's in the formatted message:
94 //!
95 //! ```
96 //! # use serde::Serialize;
97 //! # #[derive(Debug, Serialize)] pub struct Yak(String);
98 //! # impl Yak { fn shave(&mut self, _: u32) {} }
99 //! # fn find_a_razor() -> Result<u32, std::io::Error> { Ok(1) }
100 //! # #[cfg(feature = "kv_serde")]
101 //! # fn main() {
102 //! use log::{info, warn};
103 //!
104 //! pub fn shave_the_yak(yak: &mut Yak) {
105 //! info!(target: "yak_events", yak:serde; "Commencing yak shaving");
106 //!
107 //! loop {
108 //! match find_a_razor() {
109 //! Ok(razor) => {
110 //! info!(razor; "Razor located");
111 //! yak.shave(razor);
112 //! break;
113 //! }
114 //! Err(e) => {
115 //! warn!(e:err; "Unable to locate a razor, retrying");
116 //! }
117 //! }
118 //! }
119 //! }
120 //! # }
121 //! # #[cfg(not(feature = "kv_serde"))]
122 //! # fn main() {}
123 //! ```
124 //!
125 //! See the [`kv`] module documentation for more details.
126 //!
127 //! # Available logging implementations
128 //!
129 //! In order to produce log output executables have to use
130 //! a logger implementation compatible with the facade.
131 //! There are many available implementations to choose from,
132 //! here are some of the most popular ones:
133 //!
134 //! * Simple minimal loggers:
135 //! * [env_logger]
136 //! * [simple_logger]
137 //! * [simplelog]
138 //! * [pretty_env_logger]
139 //! * [stderrlog]
140 //! * [flexi_logger]
141 //! * [call_logger]
142 //! * [structured-logger]
143 //! * Complex configurable frameworks:
144 //! * [log4rs]
145 //! * [fern]
146 //! * Adaptors for other facilities:
147 //! * [syslog]
148 //! * [slog-stdlog]
149 //! * [systemd-journal-logger]
150 //! * [android_log]
151 //! * [win_dbg_logger]
152 //! * [db_logger]
153 //! * [log-to-defmt]
154 //! * [logcontrol-log]
155 //! * For WebAssembly binaries:
156 //! * [console_log]
157 //! * For dynamic libraries:
158 //! * You may need to construct an FFI-safe wrapper over `log` to initialize in your libraries
159 //! * Utilities:
160 //! * [log_err]
161 //! * [log-reload]
162 //!
163 //! # Implementing a Logger
164 //!
165 //! Loggers implement the [`Log`] trait. Here's a very basic example that simply
166 //! logs all messages at the [`Error`][level_link], [`Warn`][level_link] or
167 //! [`Info`][level_link] levels to stdout:
168 //!
169 //! ```
170 //! use log::{Record, Level, Metadata};
171 //!
172 //! struct SimpleLogger;
173 //!
174 //! impl log::Log for SimpleLogger {
175 //! fn enabled(&self, metadata: &Metadata) -> bool {
176 //! metadata.level() <= Level::Info
177 //! }
178 //!
179 //! fn log(&self, record: &Record) {
180 //! if self.enabled(record.metadata()) {
181 //! println!("{} - {}", record.level(), record.args());
182 //! }
183 //! }
184 //!
185 //! fn flush(&self) {}
186 //! }
187 //!
188 //! # fn main() {}
189 //! ```
190 //!
191 //! Loggers are installed by calling the [`set_logger`] function. The maximum
192 //! log level also needs to be adjusted via the [`set_max_level`] function. The
193 //! logging facade uses this as an optimization to improve performance of log
194 //! messages at levels that are disabled. It's important to set it, as it
195 //! defaults to [`Off`][filter_link], so no log messages will ever be captured!
196 //! In the case of our example logger, we'll want to set the maximum log level
197 //! to [`Info`][filter_link], since we ignore any [`Debug`][level_link] or
198 //! [`Trace`][level_link] level log messages. A logging implementation should
199 //! provide a function that wraps a call to [`set_logger`] and
200 //! [`set_max_level`], handling initialization of the logger:
201 //!
202 //! ```
203 //! # use log::{Level, Metadata};
204 //! # struct SimpleLogger;
205 //! # impl log::Log for SimpleLogger {
206 //! # fn enabled(&self, _: &Metadata) -> bool { false }
207 //! # fn log(&self, _: &log::Record) {}
208 //! # fn flush(&self) {}
209 //! # }
210 //! # fn main() {}
211 //! use log::{SetLoggerError, LevelFilter};
212 //!
213 //! static LOGGER: SimpleLogger = SimpleLogger;
214 //!
215 //! pub fn init() -> Result<(), SetLoggerError> {
216 //! log::set_logger(&LOGGER)
217 //! .map(|()| log::set_max_level(LevelFilter::Info))
218 //! }
219 //! ```
220 //!
221 //! Implementations that adjust their configurations at runtime should take care
222 //! to adjust the maximum log level as well.
223 //!
224 //! # Use with `std`
225 //!
226 //! `set_logger` requires you to provide a `&'static Log`, which can be hard to
227 //! obtain if your logger depends on some runtime configuration. The
228 //! `set_boxed_logger` function is available with the `std` Cargo feature. It is
229 //! identical to `set_logger` except that it takes a `Box<Log>` rather than a
230 //! `&'static Log`:
231 //!
232 //! ```
233 //! # use log::{Level, LevelFilter, Log, SetLoggerError, Metadata};
234 //! # struct SimpleLogger;
235 //! # impl log::Log for SimpleLogger {
236 //! # fn enabled(&self, _: &Metadata) -> bool { false }
237 //! # fn log(&self, _: &log::Record) {}
238 //! # fn flush(&self) {}
239 //! # }
240 //! # fn main() {}
241 //! # #[cfg(feature = "std")]
242 //! pub fn init() -> Result<(), SetLoggerError> {
243 //! log::set_boxed_logger(Box::new(SimpleLogger))
244 //! .map(|()| log::set_max_level(LevelFilter::Info))
245 //! }
246 //! ```
247 //!
248 //! # Compile time filters
249 //!
250 //! Log levels can be statically disabled at compile time by enabling one of these Cargo features:
251 //!
252 //! * `max_level_off`
253 //! * `max_level_error`
254 //! * `max_level_warn`
255 //! * `max_level_info`
256 //! * `max_level_debug`
257 //! * `max_level_trace`
258 //!
259 //! Log invocations at disabled levels will be skipped and will not even be present in the
260 //! resulting binary. These features control the value of the `STATIC_MAX_LEVEL` constant. The
261 //! logging macros check this value before logging a message. By default, no levels are disabled.
262 //!
263 //! It is possible to override this level for release builds only with the following features:
264 //!
265 //! * `release_max_level_off`
266 //! * `release_max_level_error`
267 //! * `release_max_level_warn`
268 //! * `release_max_level_info`
269 //! * `release_max_level_debug`
270 //! * `release_max_level_trace`
271 //!
272 //! Libraries should avoid using the max level features because they're global and can't be changed
273 //! once they're set.
274 //!
275 //! For example, a crate can disable trace level logs in debug builds and trace, debug, and info
276 //! level logs in release builds with the following configuration:
277 //!
278 //! ```toml
279 //! [dependencies]
280 //! log = { version = "0.4", features = ["max_level_debug", "release_max_level_warn"] }
281 //! ```
282 //! # Crate Feature Flags
283 //!
284 //! The following crate feature flags are available in addition to the filters. They are
285 //! configured in your `Cargo.toml`.
286 //!
287 //! * `std` allows use of `std` crate instead of the default `core`. Enables using `std::error` and
288 //! `set_boxed_logger` functionality.
289 //! * `serde` enables support for serialization and deserialization of `Level` and `LevelFilter`.
290 //!
291 //! ```toml
292 //! [dependencies]
293 //! log = { version = "0.4", features = ["std", "serde"] }
294 //! ```
295 //!
296 //! # Version compatibility
297 //!
298 //! The 0.3 and 0.4 versions of the `log` crate are almost entirely compatible. Log messages
299 //! made using `log` 0.3 will forward transparently to a logger implementation using `log` 0.4. Log
300 //! messages made using `log` 0.4 will forward to a logger implementation using `log` 0.3, but the
301 //! module path and file name information associated with the message will unfortunately be lost.
302 //!
303 //! [`Log`]: trait.Log.html
304 //! [level_link]: enum.Level.html
305 //! [filter_link]: enum.LevelFilter.html
306 //! [`set_logger`]: fn.set_logger.html
307 //! [`set_max_level`]: fn.set_max_level.html
308 //! [`try_set_logger_raw`]: fn.try_set_logger_raw.html
309 //! [`shutdown_logger_raw`]: fn.shutdown_logger_raw.html
310 //! [env_logger]: https://docs.rs/env_logger/*/env_logger/
311 //! [simple_logger]: https://github.com/borntyping/rust-simple_logger
312 //! [simplelog]: https://github.com/drakulix/simplelog.rs
313 //! [pretty_env_logger]: https://docs.rs/pretty_env_logger/*/pretty_env_logger/
314 //! [stderrlog]: https://docs.rs/stderrlog/*/stderrlog/
315 //! [flexi_logger]: https://docs.rs/flexi_logger/*/flexi_logger/
316 //! [call_logger]: https://docs.rs/call_logger/*/call_logger/
317 //! [syslog]: https://docs.rs/syslog/*/syslog/
318 //! [slog-stdlog]: https://docs.rs/slog-stdlog/*/slog_stdlog/
319 //! [log4rs]: https://docs.rs/log4rs/*/log4rs/
320 //! [fern]: https://docs.rs/fern/*/fern/
321 //! [systemd-journal-logger]: https://docs.rs/systemd-journal-logger/*/systemd_journal_logger/
322 //! [android_log]: https://docs.rs/android_log/*/android_log/
323 //! [win_dbg_logger]: https://docs.rs/win_dbg_logger/*/win_dbg_logger/
324 //! [db_logger]: https://docs.rs/db_logger/*/db_logger/
325 //! [log-to-defmt]: https://docs.rs/log-to-defmt/*/log_to_defmt/
326 //! [console_log]: https://docs.rs/console_log/*/console_log/
327 //! [structured-logger]: https://docs.rs/structured-logger/latest/structured_logger/
328 //! [logcontrol-log]: https://docs.rs/logcontrol-log/*/logcontrol_log/
329 //! [log_err]: https://docs.rs/log_err/*/log_err/
330 //! [log-reload]: https://docs.rs/log-reload/*/log_reload/
331
332 #![doc(
333 html_logo_url = "https://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png",
334 html_favicon_url = "https://www.rust-lang.org/favicon.ico",
335 html_root_url = "https://docs.rs/log/0.4.21"
336 )]
337 #![warn(missing_docs)]
338 #![deny(missing_debug_implementations, unconditional_recursion)]
339 #![cfg_attr(all(not(feature = "std"), not(test)), no_std)]
340 // When compiled for the rustc compiler itself we want to make sure that this is
341 // an unstable crate
342 #![cfg_attr(rustbuild, feature(staged_api, rustc_private))]
343 #![cfg_attr(rustbuild, unstable(feature = "rustc_private", issue = "27812"))]
344
345 #[cfg(all(not(feature = "std"), not(test)))]
346 extern crate core as std;
347
348 use std::cfg;
349 #[cfg(feature = "std")]
350 use std::error;
351 use std::str::FromStr;
352 use std::{cmp, fmt, mem};
353
354 #[macro_use]
355 mod macros;
356 mod serde;
357
358 #[cfg(feature = "kv")]
359 pub mod kv;
360
361 #[cfg(target_has_atomic = "ptr")]
362 use std::sync::atomic::{AtomicUsize, Ordering};
363
364 #[cfg(not(target_has_atomic = "ptr"))]
365 use std::cell::Cell;
366 #[cfg(not(target_has_atomic = "ptr"))]
367 use std::sync::atomic::Ordering;
368
369 #[cfg(not(target_has_atomic = "ptr"))]
370 struct AtomicUsize {
371 v: Cell<usize>,
372 }
373
374 #[cfg(not(target_has_atomic = "ptr"))]
375 impl AtomicUsize {
376 const fn new(v: usize) -> AtomicUsize {
377 AtomicUsize { v: Cell::new(v) }
378 }
379
380 fn load(&self, _order: Ordering) -> usize {
381 self.v.get()
382 }
383
384 fn store(&self, val: usize, _order: Ordering) {
385 self.v.set(val)
386 }
387
388 #[cfg(target_has_atomic = "ptr")]
389 fn compare_exchange(
390 &self,
391 current: usize,
392 new: usize,
393 _success: Ordering,
394 _failure: Ordering,
395 ) -> Result<usize, usize> {
396 let prev = self.v.get();
397 if current == prev {
398 self.v.set(new);
399 }
400 Ok(prev)
401 }
402 }
403
404 // Any platform without atomics is unlikely to have multiple cores, so
405 // writing via Cell will not be a race condition.
406 #[cfg(not(target_has_atomic = "ptr"))]
407 unsafe impl Sync for AtomicUsize {}
408
409 // The LOGGER static holds a pointer to the global logger. It is protected by
410 // the STATE static which determines whether LOGGER has been initialized yet.
411 static mut LOGGER: &dyn Log = &NopLogger;
412
413 static STATE: AtomicUsize = AtomicUsize::new(0);
414
415 // There are three different states that we care about: the logger's
416 // uninitialized, the logger's initializing (set_logger's been called but
417 // LOGGER hasn't actually been set yet), or the logger's active.
418 const UNINITIALIZED: usize = 0;
419 const INITIALIZING: usize = 1;
420 const INITIALIZED: usize = 2;
421
422 static MAX_LOG_LEVEL_FILTER: AtomicUsize = AtomicUsize::new(0);
423
424 static LOG_LEVEL_NAMES: [&str; 6] = ["OFF", "ERROR", "WARN", "INFO", "DEBUG", "TRACE"];
425
426 static SET_LOGGER_ERROR: &str = "attempted to set a logger after the logging system \
427 was already initialized";
428 static LEVEL_PARSE_ERROR: &str =
429 "attempted to convert a string that doesn't match an existing log level";
430
431 /// An enum representing the available verbosity levels of the logger.
432 ///
433 /// Typical usage includes: checking if a certain `Level` is enabled with
434 /// [`log_enabled!`](macro.log_enabled.html), specifying the `Level` of
435 /// [`log!`](macro.log.html), and comparing a `Level` directly to a
436 /// [`LevelFilter`](enum.LevelFilter.html).
437 #[repr(usize)]
438 #[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Debug, Hash)]
439 pub enum Level {
440 /// The "error" level.
441 ///
442 /// Designates very serious errors.
443 // This way these line up with the discriminants for LevelFilter below
444 // This works because Rust treats field-less enums the same way as C does:
445 // https://doc.rust-lang.org/reference/items/enumerations.html#custom-discriminant-values-for-field-less-enumerations
446 Error = 1,
447 /// The "warn" level.
448 ///
449 /// Designates hazardous situations.
450 Warn,
451 /// The "info" level.
452 ///
453 /// Designates useful information.
454 Info,
455 /// The "debug" level.
456 ///
457 /// Designates lower priority information.
458 Debug,
459 /// The "trace" level.
460 ///
461 /// Designates very low priority, often extremely verbose, information.
462 Trace,
463 }
464
465 impl PartialEq<LevelFilter> for Level {
466 #[inline]
467 fn eq(&self, other: &LevelFilter) -> bool {
468 *self as usize == *other as usize
469 }
470 }
471
472 impl PartialOrd<LevelFilter> for Level {
473 #[inline]
474 fn partial_cmp(&self, other: &LevelFilter) -> Option<cmp::Ordering> {
475 Some((*self as usize).cmp(&(*other as usize)))
476 }
477 }
478
479 impl FromStr for Level {
480 type Err = ParseLevelError;
481 fn from_str(level: &str) -> Result<Level, Self::Err> {
482 LOG_LEVEL_NAMES
483 .iter()
484 .position(|&name| name.eq_ignore_ascii_case(level))
485 .into_iter()
486 .filter(|&idx| idx != 0)
487 .map(|idx| Level::from_usize(idx).unwrap())
488 .next()
489 .ok_or(ParseLevelError(()))
490 }
491 }
492
493 impl fmt::Display for Level {
494 fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
495 fmt.pad(self.as_str())
496 }
497 }
498
499 impl Level {
500 fn from_usize(u: usize) -> Option<Level> {
501 match u {
502 1 => Some(Level::Error),
503 2 => Some(Level::Warn),
504 3 => Some(Level::Info),
505 4 => Some(Level::Debug),
506 5 => Some(Level::Trace),
507 _ => None,
508 }
509 }
510
511 /// Returns the most verbose logging level.
512 #[inline]
513 pub fn max() -> Level {
514 Level::Trace
515 }
516
517 /// Converts the `Level` to the equivalent `LevelFilter`.
518 #[inline]
519 pub fn to_level_filter(&self) -> LevelFilter {
520 LevelFilter::from_usize(*self as usize).unwrap()
521 }
522
523 /// Returns the string representation of the `Level`.
524 ///
525 /// This returns the same string as the `fmt::Display` implementation.
526 pub fn as_str(&self) -> &'static str {
527 LOG_LEVEL_NAMES[*self as usize]
528 }
529
530 /// Iterate through all supported logging levels.
531 ///
532 /// The order of iteration is from more severe to less severe log messages.
533 ///
534 /// # Examples
535 ///
536 /// ```
537 /// use log::Level;
538 ///
539 /// let mut levels = Level::iter();
540 ///
541 /// assert_eq!(Some(Level::Error), levels.next());
542 /// assert_eq!(Some(Level::Trace), levels.last());
543 /// ```
544 pub fn iter() -> impl Iterator<Item = Self> {
545 (1..6).map(|i| Self::from_usize(i).unwrap())
546 }
547 }
548
549 /// An enum representing the available verbosity level filters of the logger.
550 ///
551 /// A `LevelFilter` may be compared directly to a [`Level`]. Use this type
552 /// to get and set the maximum log level with [`max_level()`] and [`set_max_level`].
553 ///
554 /// [`Level`]: enum.Level.html
555 /// [`max_level()`]: fn.max_level.html
556 /// [`set_max_level`]: fn.set_max_level.html
557 #[repr(usize)]
558 #[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Debug, Hash)]
559 pub enum LevelFilter {
560 /// A level lower than all log levels.
561 Off,
562 /// Corresponds to the `Error` log level.
563 Error,
564 /// Corresponds to the `Warn` log level.
565 Warn,
566 /// Corresponds to the `Info` log level.
567 Info,
568 /// Corresponds to the `Debug` log level.
569 Debug,
570 /// Corresponds to the `Trace` log level.
571 Trace,
572 }
573
574 impl PartialEq<Level> for LevelFilter {
575 #[inline]
576 fn eq(&self, other: &Level) -> bool {
577 other.eq(self)
578 }
579 }
580
581 impl PartialOrd<Level> for LevelFilter {
582 #[inline]
583 fn partial_cmp(&self, other: &Level) -> Option<cmp::Ordering> {
584 Some((*self as usize).cmp(&(*other as usize)))
585 }
586 }
587
588 impl FromStr for LevelFilter {
589 type Err = ParseLevelError;
590 fn from_str(level: &str) -> Result<LevelFilter, Self::Err> {
591 LOG_LEVEL_NAMES
592 .iter()
593 .position(|&name| name.eq_ignore_ascii_case(level))
594 .map(|p| LevelFilter::from_usize(p).unwrap())
595 .ok_or(ParseLevelError(()))
596 }
597 }
598
599 impl fmt::Display for LevelFilter {
600 fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
601 fmt.pad(self.as_str())
602 }
603 }
604
605 impl LevelFilter {
606 fn from_usize(u: usize) -> Option<LevelFilter> {
607 match u {
608 0 => Some(LevelFilter::Off),
609 1 => Some(LevelFilter::Error),
610 2 => Some(LevelFilter::Warn),
611 3 => Some(LevelFilter::Info),
612 4 => Some(LevelFilter::Debug),
613 5 => Some(LevelFilter::Trace),
614 _ => None,
615 }
616 }
617
618 /// Returns the most verbose logging level filter.
619 #[inline]
620 pub fn max() -> LevelFilter {
621 LevelFilter::Trace
622 }
623
624 /// Converts `self` to the equivalent `Level`.
625 ///
626 /// Returns `None` if `self` is `LevelFilter::Off`.
627 #[inline]
628 pub fn to_level(&self) -> Option<Level> {
629 Level::from_usize(*self as usize)
630 }
631
632 /// Returns the string representation of the `LevelFilter`.
633 ///
634 /// This returns the same string as the `fmt::Display` implementation.
635 pub fn as_str(&self) -> &'static str {
636 LOG_LEVEL_NAMES[*self as usize]
637 }
638
639 /// Iterate through all supported filtering levels.
640 ///
641 /// The order of iteration is from less to more verbose filtering.
642 ///
643 /// # Examples
644 ///
645 /// ```
646 /// use log::LevelFilter;
647 ///
648 /// let mut levels = LevelFilter::iter();
649 ///
650 /// assert_eq!(Some(LevelFilter::Off), levels.next());
651 /// assert_eq!(Some(LevelFilter::Trace), levels.last());
652 /// ```
653 pub fn iter() -> impl Iterator<Item = Self> {
654 (0..6).map(|i| Self::from_usize(i).unwrap())
655 }
656 }
657
658 #[derive(Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Debug)]
659 enum MaybeStaticStr<'a> {
660 Static(&'static str),
661 Borrowed(&'a str),
662 }
663
664 impl<'a> MaybeStaticStr<'a> {
665 #[inline]
666 fn get(&self) -> &'a str {
667 match *self {
668 MaybeStaticStr::Static(s) => s,
669 MaybeStaticStr::Borrowed(s) => s,
670 }
671 }
672 }
673
674 /// The "payload" of a log message.
675 ///
676 /// # Use
677 ///
678 /// `Record` structures are passed as parameters to the [`log`][method.log]
679 /// method of the [`Log`] trait. Logger implementors manipulate these
680 /// structures in order to display log messages. `Record`s are automatically
681 /// created by the [`log!`] macro and so are not seen by log users.
682 ///
683 /// Note that the [`level()`] and [`target()`] accessors are equivalent to
684 /// `self.metadata().level()` and `self.metadata().target()` respectively.
685 /// These methods are provided as a convenience for users of this structure.
686 ///
687 /// # Example
688 ///
689 /// The following example shows a simple logger that displays the level,
690 /// module path, and message of any `Record` that is passed to it.
691 ///
692 /// ```
693 /// struct SimpleLogger;
694 ///
695 /// impl log::Log for SimpleLogger {
696 /// fn enabled(&self, _metadata: &log::Metadata) -> bool {
697 /// true
698 /// }
699 ///
700 /// fn log(&self, record: &log::Record) {
701 /// if !self.enabled(record.metadata()) {
702 /// return;
703 /// }
704 ///
705 /// println!("{}:{} -- {}",
706 /// record.level(),
707 /// record.target(),
708 /// record.args());
709 /// }
710 /// fn flush(&self) {}
711 /// }
712 /// ```
713 ///
714 /// [method.log]: trait.Log.html#tymethod.log
715 /// [`Log`]: trait.Log.html
716 /// [`log!`]: macro.log.html
717 /// [`level()`]: struct.Record.html#method.level
718 /// [`target()`]: struct.Record.html#method.target
719 #[derive(Clone, Debug)]
720 pub struct Record<'a> {
721 metadata: Metadata<'a>,
722 args: fmt::Arguments<'a>,
723 module_path: Option<MaybeStaticStr<'a>>,
724 file: Option<MaybeStaticStr<'a>>,
725 line: Option<u32>,
726 #[cfg(feature = "kv")]
727 key_values: KeyValues<'a>,
728 }
729
730 // This wrapper type is only needed so we can
731 // `#[derive(Debug)]` on `Record`. It also
732 // provides a useful `Debug` implementation for
733 // the underlying `Source`.
734 #[cfg(feature = "kv")]
735 #[derive(Clone)]
736 struct KeyValues<'a>(&'a dyn kv::Source);
737
738 #[cfg(feature = "kv")]
739 impl<'a> fmt::Debug for KeyValues<'a> {
740 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
741 let mut visitor = f.debug_map();
742 self.0.visit(&mut visitor).map_err(|_| fmt::Error)?;
743 visitor.finish()
744 }
745 }
746
747 impl<'a> Record<'a> {
748 /// Returns a new builder.
749 #[inline]
750 pub fn builder() -> RecordBuilder<'a> {
751 RecordBuilder::new()
752 }
753
754 /// The message body.
755 #[inline]
756 pub fn args(&self) -> &fmt::Arguments<'a> {
757 &self.args
758 }
759
760 /// Metadata about the log directive.
761 #[inline]
762 pub fn metadata(&self) -> &Metadata<'a> {
763 &self.metadata
764 }
765
766 /// The verbosity level of the message.
767 #[inline]
768 pub fn level(&self) -> Level {
769 self.metadata.level()
770 }
771
772 /// The name of the target of the directive.
773 #[inline]
774 pub fn target(&self) -> &'a str {
775 self.metadata.target()
776 }
777
778 /// The module path of the message.
779 #[inline]
780 pub fn module_path(&self) -> Option<&'a str> {
781 self.module_path.map(|s| s.get())
782 }
783
784 /// The module path of the message, if it is a `'static` string.
785 #[inline]
786 pub fn module_path_static(&self) -> Option<&'static str> {
787 match self.module_path {
788 Some(MaybeStaticStr::Static(s)) => Some(s),
789 _ => None,
790 }
791 }
792
793 /// The source file containing the message.
794 #[inline]
795 pub fn file(&self) -> Option<&'a str> {
796 self.file.map(|s| s.get())
797 }
798
799 /// The source file containing the message, if it is a `'static` string.
800 #[inline]
801 pub fn file_static(&self) -> Option<&'static str> {
802 match self.file {
803 Some(MaybeStaticStr::Static(s)) => Some(s),
804 _ => None,
805 }
806 }
807
808 /// The line containing the message.
809 #[inline]
810 pub fn line(&self) -> Option<u32> {
811 self.line
812 }
813
814 /// The structured key-value pairs associated with the message.
815 #[cfg(feature = "kv")]
816 #[inline]
817 pub fn key_values(&self) -> &dyn kv::Source {
818 self.key_values.0
819 }
820
821 /// Create a new [`RecordBuilder`](struct.RecordBuilder.html) based on this record.
822 #[cfg(feature = "kv")]
823 #[inline]
824 pub fn to_builder(&self) -> RecordBuilder {
825 RecordBuilder {
826 record: Record {
827 metadata: Metadata {
828 level: self.metadata.level,
829 target: self.metadata.target,
830 },
831 args: self.args,
832 module_path: self.module_path,
833 file: self.file,
834 line: self.line,
835 key_values: self.key_values.clone(),
836 },
837 }
838 }
839 }
840
841 /// Builder for [`Record`](struct.Record.html).
842 ///
843 /// Typically should only be used by log library creators or for testing and "shim loggers".
844 /// The `RecordBuilder` can set the different parameters of `Record` object, and returns
845 /// the created object when `build` is called.
846 ///
847 /// # Examples
848 ///
849 /// ```
850 /// use log::{Level, Record};
851 ///
852 /// let record = Record::builder()
853 /// .args(format_args!("Error!"))
854 /// .level(Level::Error)
855 /// .target("myApp")
856 /// .file(Some("server.rs"))
857 /// .line(Some(144))
858 /// .module_path(Some("server"))
859 /// .build();
860 /// ```
861 ///
862 /// Alternatively, use [`MetadataBuilder`](struct.MetadataBuilder.html):
863 ///
864 /// ```
865 /// use log::{Record, Level, MetadataBuilder};
866 ///
867 /// let error_metadata = MetadataBuilder::new()
868 /// .target("myApp")
869 /// .level(Level::Error)
870 /// .build();
871 ///
872 /// let record = Record::builder()
873 /// .metadata(error_metadata)
874 /// .args(format_args!("Error!"))
875 /// .line(Some(433))
876 /// .file(Some("app.rs"))
877 /// .module_path(Some("server"))
878 /// .build();
879 /// ```
880 #[derive(Debug)]
881 pub struct RecordBuilder<'a> {
882 record: Record<'a>,
883 }
884
885 impl<'a> RecordBuilder<'a> {
886 /// Construct new `RecordBuilder`.
887 ///
888 /// The default options are:
889 ///
890 /// - `args`: [`format_args!("")`]
891 /// - `metadata`: [`Metadata::builder().build()`]
892 /// - `module_path`: `None`
893 /// - `file`: `None`
894 /// - `line`: `None`
895 ///
896 /// [`format_args!("")`]: https://doc.rust-lang.org/std/macro.format_args.html
897 /// [`Metadata::builder().build()`]: struct.MetadataBuilder.html#method.build
898 #[inline]
899 pub fn new() -> RecordBuilder<'a> {
900 RecordBuilder {
901 record: Record {
902 args: format_args!(""),
903 metadata: Metadata::builder().build(),
904 module_path: None,
905 file: None,
906 line: None,
907 #[cfg(feature = "kv")]
908 key_values: KeyValues(&None::<(kv::Key, kv::Value)>),
909 },
910 }
911 }
912
913 /// Set [`args`](struct.Record.html#method.args).
914 #[inline]
915 pub fn args(&mut self, args: fmt::Arguments<'a>) -> &mut RecordBuilder<'a> {
916 self.record.args = args;
917 self
918 }
919
920 /// Set [`metadata`](struct.Record.html#method.metadata). Construct a `Metadata` object with [`MetadataBuilder`](struct.MetadataBuilder.html).
921 #[inline]
922 pub fn metadata(&mut self, metadata: Metadata<'a>) -> &mut RecordBuilder<'a> {
923 self.record.metadata = metadata;
924 self
925 }
926
927 /// Set [`Metadata::level`](struct.Metadata.html#method.level).
928 #[inline]
929 pub fn level(&mut self, level: Level) -> &mut RecordBuilder<'a> {
930 self.record.metadata.level = level;
931 self
932 }
933
934 /// Set [`Metadata::target`](struct.Metadata.html#method.target)
935 #[inline]
936 pub fn target(&mut self, target: &'a str) -> &mut RecordBuilder<'a> {
937 self.record.metadata.target = target;
938 self
939 }
940
941 /// Set [`module_path`](struct.Record.html#method.module_path)
942 #[inline]
943 pub fn module_path(&mut self, path: Option<&'a str>) -> &mut RecordBuilder<'a> {
944 self.record.module_path = path.map(MaybeStaticStr::Borrowed);
945 self
946 }
947
948 /// Set [`module_path`](struct.Record.html#method.module_path) to a `'static` string
949 #[inline]
950 pub fn module_path_static(&mut self, path: Option<&'static str>) -> &mut RecordBuilder<'a> {
951 self.record.module_path = path.map(MaybeStaticStr::Static);
952 self
953 }
954
955 /// Set [`file`](struct.Record.html#method.file)
956 #[inline]
957 pub fn file(&mut self, file: Option<&'a str>) -> &mut RecordBuilder<'a> {
958 self.record.file = file.map(MaybeStaticStr::Borrowed);
959 self
960 }
961
962 /// Set [`file`](struct.Record.html#method.file) to a `'static` string.
963 #[inline]
964 pub fn file_static(&mut self, file: Option<&'static str>) -> &mut RecordBuilder<'a> {
965 self.record.file = file.map(MaybeStaticStr::Static);
966 self
967 }
968
969 /// Set [`line`](struct.Record.html#method.line)
970 #[inline]
971 pub fn line(&mut self, line: Option<u32>) -> &mut RecordBuilder<'a> {
972 self.record.line = line;
973 self
974 }
975
976 /// Set [`key_values`](struct.Record.html#method.key_values)
977 #[cfg(feature = "kv")]
978 #[inline]
979 pub fn key_values(&mut self, kvs: &'a dyn kv::Source) -> &mut RecordBuilder<'a> {
980 self.record.key_values = KeyValues(kvs);
981 self
982 }
983
984 /// Invoke the builder and return a `Record`
985 #[inline]
986 pub fn build(&self) -> Record<'a> {
987 self.record.clone()
988 }
989 }
990
991 impl<'a> Default for RecordBuilder<'a> {
992 fn default() -> Self {
993 Self::new()
994 }
995 }
996
997 /// Metadata about a log message.
998 ///
999 /// # Use
1000 ///
1001 /// `Metadata` structs are created when users of the library use
1002 /// logging macros.
1003 ///
1004 /// They are consumed by implementations of the `Log` trait in the
1005 /// `enabled` method.
1006 ///
1007 /// `Record`s use `Metadata` to determine the log message's severity
1008 /// and target.
1009 ///
1010 /// Users should use the `log_enabled!` macro in their code to avoid
1011 /// constructing expensive log messages.
1012 ///
1013 /// # Examples
1014 ///
1015 /// ```
1016 /// use log::{Record, Level, Metadata};
1017 ///
1018 /// struct MyLogger;
1019 ///
1020 /// impl log::Log for MyLogger {
1021 /// fn enabled(&self, metadata: &Metadata) -> bool {
1022 /// metadata.level() <= Level::Info
1023 /// }
1024 ///
1025 /// fn log(&self, record: &Record) {
1026 /// if self.enabled(record.metadata()) {
1027 /// println!("{} - {}", record.level(), record.args());
1028 /// }
1029 /// }
1030 /// fn flush(&self) {}
1031 /// }
1032 ///
1033 /// # fn main(){}
1034 /// ```
1035 #[derive(Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Debug)]
1036 pub struct Metadata<'a> {
1037 level: Level,
1038 target: &'a str,
1039 }
1040
1041 impl<'a> Metadata<'a> {
1042 /// Returns a new builder.
1043 #[inline]
1044 pub fn builder() -> MetadataBuilder<'a> {
1045 MetadataBuilder::new()
1046 }
1047
1048 /// The verbosity level of the message.
1049 #[inline]
1050 pub fn level(&self) -> Level {
1051 self.level
1052 }
1053
1054 /// The name of the target of the directive.
1055 #[inline]
1056 pub fn target(&self) -> &'a str {
1057 self.target
1058 }
1059 }
1060
1061 /// Builder for [`Metadata`](struct.Metadata.html).
1062 ///
1063 /// Typically should only be used by log library creators or for testing and "shim loggers".
1064 /// The `MetadataBuilder` can set the different parameters of a `Metadata` object, and returns
1065 /// the created object when `build` is called.
1066 ///
1067 /// # Example
1068 ///
1069 /// ```
1070 /// let target = "myApp";
1071 /// use log::{Level, MetadataBuilder};
1072 /// let metadata = MetadataBuilder::new()
1073 /// .level(Level::Debug)
1074 /// .target(target)
1075 /// .build();
1076 /// ```
1077 #[derive(Eq, PartialEq, Ord, PartialOrd, Hash, Debug)]
1078 pub struct MetadataBuilder<'a> {
1079 metadata: Metadata<'a>,
1080 }
1081
1082 impl<'a> MetadataBuilder<'a> {
1083 /// Construct a new `MetadataBuilder`.
1084 ///
1085 /// The default options are:
1086 ///
1087 /// - `level`: `Level::Info`
1088 /// - `target`: `""`
1089 #[inline]
1090 pub fn new() -> MetadataBuilder<'a> {
1091 MetadataBuilder {
1092 metadata: Metadata {
1093 level: Level::Info,
1094 target: "",
1095 },
1096 }
1097 }
1098
1099 /// Setter for [`level`](struct.Metadata.html#method.level).
1100 #[inline]
1101 pub fn level(&mut self, arg: Level) -> &mut MetadataBuilder<'a> {
1102 self.metadata.level = arg;
1103 self
1104 }
1105
1106 /// Setter for [`target`](struct.Metadata.html#method.target).
1107 #[inline]
1108 pub fn target(&mut self, target: &'a str) -> &mut MetadataBuilder<'a> {
1109 self.metadata.target = target;
1110 self
1111 }
1112
1113 /// Returns a `Metadata` object.
1114 #[inline]
1115 pub fn build(&self) -> Metadata<'a> {
1116 self.metadata.clone()
1117 }
1118 }
1119
1120 impl<'a> Default for MetadataBuilder<'a> {
1121 fn default() -> Self {
1122 Self::new()
1123 }
1124 }
1125
1126 /// A trait encapsulating the operations required of a logger.
1127 pub trait Log: Sync + Send {
1128 /// Determines if a log message with the specified metadata would be
1129 /// logged.
1130 ///
1131 /// This is used by the `log_enabled!` macro to allow callers to avoid
1132 /// expensive computation of log message arguments if the message would be
1133 /// discarded anyway.
1134 ///
1135 /// # For implementors
1136 ///
1137 /// This method isn't called automatically by the `log!` macros.
1138 /// It's up to an implementation of the `Log` trait to call `enabled` in its own
1139 /// `log` method implementation to guarantee that filtering is applied.
1140 fn enabled(&self, metadata: &Metadata) -> bool;
1141
1142 /// Logs the `Record`.
1143 ///
1144 /// # For implementors
1145 ///
1146 /// Note that `enabled` is *not* necessarily called before this method.
1147 /// Implementations of `log` should perform all necessary filtering
1148 /// internally.
1149 fn log(&self, record: &Record);
1150
1151 /// Flushes any buffered records.
1152 fn flush(&self);
1153 }
1154
1155 // Just used as a dummy initial value for LOGGER
1156 struct NopLogger;
1157
1158 impl Log for NopLogger {
1159 fn enabled(&self, _: &Metadata) -> bool {
1160 false
1161 }
1162
1163 fn log(&self, _: &Record) {}
1164 fn flush(&self) {}
1165 }
1166
1167 impl<T> Log for &'_ T
1168 where
1169 T: ?Sized + Log,
1170 {
1171 fn enabled(&self, metadata: &Metadata) -> bool {
1172 (**self).enabled(metadata)
1173 }
1174
1175 fn log(&self, record: &Record) {
1176 (**self).log(record);
1177 }
1178 fn flush(&self) {
1179 (**self).flush();
1180 }
1181 }
1182
1183 #[cfg(feature = "std")]
1184 impl<T> Log for std::boxed::Box<T>
1185 where
1186 T: ?Sized + Log,
1187 {
1188 fn enabled(&self, metadata: &Metadata) -> bool {
1189 self.as_ref().enabled(metadata)
1190 }
1191
1192 fn log(&self, record: &Record) {
1193 self.as_ref().log(record);
1194 }
1195 fn flush(&self) {
1196 self.as_ref().flush();
1197 }
1198 }
1199
1200 #[cfg(feature = "std")]
1201 impl<T> Log for std::sync::Arc<T>
1202 where
1203 T: ?Sized + Log,
1204 {
1205 fn enabled(&self, metadata: &Metadata) -> bool {
1206 self.as_ref().enabled(metadata)
1207 }
1208
1209 fn log(&self, record: &Record) {
1210 self.as_ref().log(record);
1211 }
1212 fn flush(&self) {
1213 self.as_ref().flush();
1214 }
1215 }
1216
1217 /// Sets the global maximum log level.
1218 ///
1219 /// Generally, this should only be called by the active logging implementation.
1220 ///
1221 /// Note that `Trace` is the maximum level, because it provides the maximum amount of detail in the emitted logs.
1222 #[inline]
1223 #[cfg(target_has_atomic = "ptr")]
1224 pub fn set_max_level(level: LevelFilter) {
1225 MAX_LOG_LEVEL_FILTER.store(level as usize, Ordering::Relaxed);
1226 }
1227
1228 /// A thread-unsafe version of [`set_max_level`].
1229 ///
1230 /// This function is available on all platforms, even those that do not have
1231 /// support for atomics that is needed by [`set_max_level`].
1232 ///
1233 /// In almost all cases, [`set_max_level`] should be preferred.
1234 ///
1235 /// # Safety
1236 ///
1237 /// This function is only safe to call when no other level setting function is
1238 /// called while this function still executes.
1239 ///
1240 /// This can be upheld by (for example) making sure that **there are no other
1241 /// threads**, and (on embedded) that **interrupts are disabled**.
1242 ///
1243 /// Is is safe to use all other logging functions while this function runs
1244 /// (including all logging macros).
1245 ///
1246 /// [`set_max_level`]: fn.set_max_level.html
1247 #[inline]
1248 pub unsafe fn set_max_level_racy(level: LevelFilter) {
1249 // `MAX_LOG_LEVEL_FILTER` uses a `Cell` as the underlying primitive when a
1250 // platform doesn't support `target_has_atomic = "ptr"`, so even though this looks the same
1251 // as `set_max_level` it may have different safety properties.
1252 MAX_LOG_LEVEL_FILTER.store(level as usize, Ordering::Relaxed);
1253 }
1254
1255 /// Returns the current maximum log level.
1256 ///
1257 /// The [`log!`], [`error!`], [`warn!`], [`info!`], [`debug!`], and [`trace!`] macros check
1258 /// this value and discard any message logged at a higher level. The maximum
1259 /// log level is set by the [`set_max_level`] function.
1260 ///
1261 /// [`log!`]: macro.log.html
1262 /// [`error!`]: macro.error.html
1263 /// [`warn!`]: macro.warn.html
1264 /// [`info!`]: macro.info.html
1265 /// [`debug!`]: macro.debug.html
1266 /// [`trace!`]: macro.trace.html
1267 /// [`set_max_level`]: fn.set_max_level.html
1268 #[inline(always)]
1269 pub fn max_level() -> LevelFilter {
1270 // Since `LevelFilter` is `repr(usize)`,
1271 // this transmute is sound if and only if `MAX_LOG_LEVEL_FILTER`
1272 // is set to a usize that is a valid discriminant for `LevelFilter`.
1273 // Since `MAX_LOG_LEVEL_FILTER` is private, the only time it's set
1274 // is by `set_max_level` above, i.e. by casting a `LevelFilter` to `usize`.
1275 // So any usize stored in `MAX_LOG_LEVEL_FILTER` is a valid discriminant.
1276 unsafe { mem::transmute(MAX_LOG_LEVEL_FILTER.load(Ordering::Relaxed)) }
1277 }
1278
1279 /// Sets the global logger to a `Box<Log>`.
1280 ///
1281 /// This is a simple convenience wrapper over `set_logger`, which takes a
1282 /// `Box<Log>` rather than a `&'static Log`. See the documentation for
1283 /// [`set_logger`] for more details.
1284 ///
1285 /// Requires the `std` feature.
1286 ///
1287 /// # Errors
1288 ///
1289 /// An error is returned if a logger has already been set.
1290 ///
1291 /// [`set_logger`]: fn.set_logger.html
1292 #[cfg(all(feature = "std", target_has_atomic = "ptr"))]
1293 pub fn set_boxed_logger(logger: Box<dyn Log>) -> Result<(), SetLoggerError> {
1294 set_logger_inner(|| Box::leak(logger))
1295 }
1296
1297 /// Sets the global logger to a `&'static Log`.
1298 ///
1299 /// This function may only be called once in the lifetime of a program. Any log
1300 /// events that occur before the call to `set_logger` completes will be ignored.
1301 ///
1302 /// This function does not typically need to be called manually. Logger
1303 /// implementations should provide an initialization method that installs the
1304 /// logger internally.
1305 ///
1306 /// # Availability
1307 ///
1308 /// This method is available even when the `std` feature is disabled. However,
1309 /// it is currently unavailable on `thumbv6` targets, which lack support for
1310 /// some atomic operations which are used by this function. Even on those
1311 /// targets, [`set_logger_racy`] will be available.
1312 ///
1313 /// # Errors
1314 ///
1315 /// An error is returned if a logger has already been set.
1316 ///
1317 /// # Examples
1318 ///
1319 /// ```
1320 /// use log::{error, info, warn, Record, Level, Metadata, LevelFilter};
1321 ///
1322 /// static MY_LOGGER: MyLogger = MyLogger;
1323 ///
1324 /// struct MyLogger;
1325 ///
1326 /// impl log::Log for MyLogger {
1327 /// fn enabled(&self, metadata: &Metadata) -> bool {
1328 /// metadata.level() <= Level::Info
1329 /// }
1330 ///
1331 /// fn log(&self, record: &Record) {
1332 /// if self.enabled(record.metadata()) {
1333 /// println!("{} - {}", record.level(), record.args());
1334 /// }
1335 /// }
1336 /// fn flush(&self) {}
1337 /// }
1338 ///
1339 /// # fn main(){
1340 /// log::set_logger(&MY_LOGGER).unwrap();
1341 /// log::set_max_level(LevelFilter::Info);
1342 ///
1343 /// info!("hello log");
1344 /// warn!("warning");
1345 /// error!("oops");
1346 /// # }
1347 /// ```
1348 ///
1349 /// [`set_logger_racy`]: fn.set_logger_racy.html
1350 #[cfg(target_has_atomic = "ptr")]
1351 pub fn set_logger(logger: &'static dyn Log) -> Result<(), SetLoggerError> {
1352 set_logger_inner(|| logger)
1353 }
1354
1355 #[cfg(target_has_atomic = "ptr")]
1356 fn set_logger_inner<F>(make_logger: F) -> Result<(), SetLoggerError>
1357 where
1358 F: FnOnce() -> &'static dyn Log,
1359 {
1360 let old_state = match STATE.compare_exchange(
1361 UNINITIALIZED,
1362 INITIALIZING,
1363 Ordering::SeqCst,
1364 Ordering::SeqCst,
1365 ) {
1366 Ok(s) | Err(s) => s,
1367 };
1368 match old_state {
1369 UNINITIALIZED => {
1370 unsafe {
1371 LOGGER = make_logger();
1372 }
1373 STATE.store(INITIALIZED, Ordering::SeqCst);
1374 Ok(())
1375 }
1376 INITIALIZING => {
1377 while STATE.load(Ordering::SeqCst) == INITIALIZING {
1378 // TODO: replace with `hint::spin_loop` once MSRV is 1.49.0.
1379 #[allow(deprecated)]
1380 std::sync::atomic::spin_loop_hint();
1381 }
1382 Err(SetLoggerError(()))
1383 }
1384 _ => Err(SetLoggerError(())),
1385 }
1386 }
1387
1388 /// A thread-unsafe version of [`set_logger`].
1389 ///
1390 /// This function is available on all platforms, even those that do not have
1391 /// support for atomics that is needed by [`set_logger`].
1392 ///
1393 /// In almost all cases, [`set_logger`] should be preferred.
1394 ///
1395 /// # Safety
1396 ///
1397 /// This function is only safe to call when no other logger initialization
1398 /// function is called while this function still executes.
1399 ///
1400 /// This can be upheld by (for example) making sure that **there are no other
1401 /// threads**, and (on embedded) that **interrupts are disabled**.
1402 ///
1403 /// It is safe to use other logging functions while this function runs
1404 /// (including all logging macros).
1405 ///
1406 /// [`set_logger`]: fn.set_logger.html
1407 pub unsafe fn set_logger_racy(logger: &'static dyn Log) -> Result<(), SetLoggerError> {
1408 match STATE.load(Ordering::SeqCst) {
1409 UNINITIALIZED => {
1410 LOGGER = logger;
1411 STATE.store(INITIALIZED, Ordering::SeqCst);
1412 Ok(())
1413 }
1414 INITIALIZING => {
1415 // This is just plain UB, since we were racing another initialization function
1416 unreachable!("set_logger_racy must not be used with other initialization functions")
1417 }
1418 _ => Err(SetLoggerError(())),
1419 }
1420 }
1421
1422 /// The type returned by [`set_logger`] if [`set_logger`] has already been called.
1423 ///
1424 /// [`set_logger`]: fn.set_logger.html
1425 #[allow(missing_copy_implementations)]
1426 #[derive(Debug)]
1427 pub struct SetLoggerError(());
1428
1429 impl fmt::Display for SetLoggerError {
1430 fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
1431 fmt.write_str(SET_LOGGER_ERROR)
1432 }
1433 }
1434
1435 // The Error trait is not available in libcore
1436 #[cfg(feature = "std")]
1437 impl error::Error for SetLoggerError {}
1438
1439 /// The type returned by [`from_str`] when the string doesn't match any of the log levels.
1440 ///
1441 /// [`from_str`]: https://doc.rust-lang.org/std/str/trait.FromStr.html#tymethod.from_str
1442 #[allow(missing_copy_implementations)]
1443 #[derive(Debug, PartialEq, Eq)]
1444 pub struct ParseLevelError(());
1445
1446 impl fmt::Display for ParseLevelError {
1447 fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
1448 fmt.write_str(LEVEL_PARSE_ERROR)
1449 }
1450 }
1451
1452 // The Error trait is not available in libcore
1453 #[cfg(feature = "std")]
1454 impl error::Error for ParseLevelError {}
1455
1456 /// Returns a reference to the logger.
1457 ///
1458 /// If a logger has not been set, a no-op implementation is returned.
1459 pub fn logger() -> &'static dyn Log {
1460 // Acquire memory ordering guarantees that current thread would see any
1461 // memory writes that happened before store of the value
1462 // into `STATE` with memory ordering `Release` or stronger.
1463 //
1464 // Since the value `INITIALIZED` is written only after `LOGGER` was
1465 // initialized, observing it after `Acquire` load here makes both
1466 // write to the `LOGGER` static and initialization of the logger
1467 // internal state synchronized with current thread.
1468 if STATE.load(Ordering::Acquire) != INITIALIZED {
1469 static NOP: NopLogger = NopLogger;
1470 &NOP
1471 } else {
1472 unsafe { LOGGER }
1473 }
1474 }
1475
1476 // WARNING: this is not part of the crate's public API and is subject to change at any time
1477 #[doc(hidden)]
1478 pub mod __private_api;
1479
1480 /// The statically resolved maximum log level.
1481 ///
1482 /// See the crate level documentation for information on how to configure this.
1483 ///
1484 /// This value is checked by the log macros, but not by the `Log`ger returned by
1485 /// the [`logger`] function. Code that manually calls functions on that value
1486 /// should compare the level against this value.
1487 ///
1488 /// [`logger`]: fn.logger.html
1489 pub const STATIC_MAX_LEVEL: LevelFilter = match cfg!(debug_assertions) {
1490 false if cfg!(feature = "release_max_level_off") => LevelFilter::Off,
1491 false if cfg!(feature = "release_max_level_error") => LevelFilter::Error,
1492 false if cfg!(feature = "release_max_level_warn") => LevelFilter::Warn,
1493 false if cfg!(feature = "release_max_level_info") => LevelFilter::Info,
1494 false if cfg!(feature = "release_max_level_debug") => LevelFilter::Debug,
1495 false if cfg!(feature = "release_max_level_trace") => LevelFilter::Trace,
1496 _ if cfg!(feature = "max_level_off") => LevelFilter::Off,
1497 _ if cfg!(feature = "max_level_error") => LevelFilter::Error,
1498 _ if cfg!(feature = "max_level_warn") => LevelFilter::Warn,
1499 _ if cfg!(feature = "max_level_info") => LevelFilter::Info,
1500 _ if cfg!(feature = "max_level_debug") => LevelFilter::Debug,
1501 _ => LevelFilter::Trace,
1502 };
1503
1504 #[cfg(test)]
1505 mod tests {
1506 use super::{Level, LevelFilter, ParseLevelError, STATIC_MAX_LEVEL};
1507
1508 #[test]
1509 fn test_levelfilter_from_str() {
1510 let tests = [
1511 ("off", Ok(LevelFilter::Off)),
1512 ("error", Ok(LevelFilter::Error)),
1513 ("warn", Ok(LevelFilter::Warn)),
1514 ("info", Ok(LevelFilter::Info)),
1515 ("debug", Ok(LevelFilter::Debug)),
1516 ("trace", Ok(LevelFilter::Trace)),
1517 ("OFF", Ok(LevelFilter::Off)),
1518 ("ERROR", Ok(LevelFilter::Error)),
1519 ("WARN", Ok(LevelFilter::Warn)),
1520 ("INFO", Ok(LevelFilter::Info)),
1521 ("DEBUG", Ok(LevelFilter::Debug)),
1522 ("TRACE", Ok(LevelFilter::Trace)),
1523 ("asdf", Err(ParseLevelError(()))),
1524 ];
1525 for &(s, ref expected) in &tests {
1526 assert_eq!(expected, &s.parse());
1527 }
1528 }
1529
1530 #[test]
1531 fn test_level_from_str() {
1532 let tests = [
1533 ("OFF", Err(ParseLevelError(()))),
1534 ("error", Ok(Level::Error)),
1535 ("warn", Ok(Level::Warn)),
1536 ("info", Ok(Level::Info)),
1537 ("debug", Ok(Level::Debug)),
1538 ("trace", Ok(Level::Trace)),
1539 ("ERROR", Ok(Level::Error)),
1540 ("WARN", Ok(Level::Warn)),
1541 ("INFO", Ok(Level::Info)),
1542 ("DEBUG", Ok(Level::Debug)),
1543 ("TRACE", Ok(Level::Trace)),
1544 ("asdf", Err(ParseLevelError(()))),
1545 ];
1546 for &(s, ref expected) in &tests {
1547 assert_eq!(expected, &s.parse());
1548 }
1549 }
1550
1551 #[test]
1552 fn test_level_as_str() {
1553 let tests = &[
1554 (Level::Error, "ERROR"),
1555 (Level::Warn, "WARN"),
1556 (Level::Info, "INFO"),
1557 (Level::Debug, "DEBUG"),
1558 (Level::Trace, "TRACE"),
1559 ];
1560 for (input, expected) in tests {
1561 assert_eq!(*expected, input.as_str());
1562 }
1563 }
1564
1565 #[test]
1566 fn test_level_show() {
1567 assert_eq!("INFO", Level::Info.to_string());
1568 assert_eq!("ERROR", Level::Error.to_string());
1569 }
1570
1571 #[test]
1572 fn test_levelfilter_show() {
1573 assert_eq!("OFF", LevelFilter::Off.to_string());
1574 assert_eq!("ERROR", LevelFilter::Error.to_string());
1575 }
1576
1577 #[test]
1578 fn test_cross_cmp() {
1579 assert!(Level::Debug > LevelFilter::Error);
1580 assert!(LevelFilter::Warn < Level::Trace);
1581 assert!(LevelFilter::Off < Level::Error);
1582 }
1583
1584 #[test]
1585 fn test_cross_eq() {
1586 assert!(Level::Error == LevelFilter::Error);
1587 assert!(LevelFilter::Off != Level::Error);
1588 assert!(Level::Trace == LevelFilter::Trace);
1589 }
1590
1591 #[test]
1592 fn test_to_level() {
1593 assert_eq!(Some(Level::Error), LevelFilter::Error.to_level());
1594 assert_eq!(None, LevelFilter::Off.to_level());
1595 assert_eq!(Some(Level::Debug), LevelFilter::Debug.to_level());
1596 }
1597
1598 #[test]
1599 fn test_to_level_filter() {
1600 assert_eq!(LevelFilter::Error, Level::Error.to_level_filter());
1601 assert_eq!(LevelFilter::Trace, Level::Trace.to_level_filter());
1602 }
1603
1604 #[test]
1605 fn test_level_filter_as_str() {
1606 let tests = &[
1607 (LevelFilter::Off, "OFF"),
1608 (LevelFilter::Error, "ERROR"),
1609 (LevelFilter::Warn, "WARN"),
1610 (LevelFilter::Info, "INFO"),
1611 (LevelFilter::Debug, "DEBUG"),
1612 (LevelFilter::Trace, "TRACE"),
1613 ];
1614 for (input, expected) in tests {
1615 assert_eq!(*expected, input.as_str());
1616 }
1617 }
1618
1619 #[test]
1620 #[cfg_attr(not(debug_assertions), ignore)]
1621 fn test_static_max_level_debug() {
1622 if cfg!(feature = "max_level_off") {
1623 assert_eq!(STATIC_MAX_LEVEL, LevelFilter::Off);
1624 } else if cfg!(feature = "max_level_error") {
1625 assert_eq!(STATIC_MAX_LEVEL, LevelFilter::Error);
1626 } else if cfg!(feature = "max_level_warn") {
1627 assert_eq!(STATIC_MAX_LEVEL, LevelFilter::Warn);
1628 } else if cfg!(feature = "max_level_info") {
1629 assert_eq!(STATIC_MAX_LEVEL, LevelFilter::Info);
1630 } else if cfg!(feature = "max_level_debug") {
1631 assert_eq!(STATIC_MAX_LEVEL, LevelFilter::Debug);
1632 } else {
1633 assert_eq!(STATIC_MAX_LEVEL, LevelFilter::Trace);
1634 }
1635 }
1636
1637 #[test]
1638 #[cfg_attr(debug_assertions, ignore)]
1639 fn test_static_max_level_release() {
1640 if cfg!(feature = "release_max_level_off") {
1641 assert_eq!(STATIC_MAX_LEVEL, LevelFilter::Off);
1642 } else if cfg!(feature = "release_max_level_error") {
1643 assert_eq!(STATIC_MAX_LEVEL, LevelFilter::Error);
1644 } else if cfg!(feature = "release_max_level_warn") {
1645 assert_eq!(STATIC_MAX_LEVEL, LevelFilter::Warn);
1646 } else if cfg!(feature = "release_max_level_info") {
1647 assert_eq!(STATIC_MAX_LEVEL, LevelFilter::Info);
1648 } else if cfg!(feature = "release_max_level_debug") {
1649 assert_eq!(STATIC_MAX_LEVEL, LevelFilter::Debug);
1650 } else if cfg!(feature = "release_max_level_trace") {
1651 assert_eq!(STATIC_MAX_LEVEL, LevelFilter::Trace);
1652 } else if cfg!(feature = "max_level_off") {
1653 assert_eq!(STATIC_MAX_LEVEL, LevelFilter::Off);
1654 } else if cfg!(feature = "max_level_error") {
1655 assert_eq!(STATIC_MAX_LEVEL, LevelFilter::Error);
1656 } else if cfg!(feature = "max_level_warn") {
1657 assert_eq!(STATIC_MAX_LEVEL, LevelFilter::Warn);
1658 } else if cfg!(feature = "max_level_info") {
1659 assert_eq!(STATIC_MAX_LEVEL, LevelFilter::Info);
1660 } else if cfg!(feature = "max_level_debug") {
1661 assert_eq!(STATIC_MAX_LEVEL, LevelFilter::Debug);
1662 } else {
1663 assert_eq!(STATIC_MAX_LEVEL, LevelFilter::Trace);
1664 }
1665 }
1666
1667 #[test]
1668 #[cfg(feature = "std")]
1669 fn test_error_trait() {
1670 use super::SetLoggerError;
1671 let e = SetLoggerError(());
1672 assert_eq!(
1673 &e.to_string(),
1674 "attempted to set a logger after the logging system \
1675 was already initialized"
1676 );
1677 }
1678
1679 #[test]
1680 fn test_metadata_builder() {
1681 use super::MetadataBuilder;
1682 let target = "myApp";
1683 let metadata_test = MetadataBuilder::new()
1684 .level(Level::Debug)
1685 .target(target)
1686 .build();
1687 assert_eq!(metadata_test.level(), Level::Debug);
1688 assert_eq!(metadata_test.target(), "myApp");
1689 }
1690
1691 #[test]
1692 fn test_metadata_convenience_builder() {
1693 use super::Metadata;
1694 let target = "myApp";
1695 let metadata_test = Metadata::builder()
1696 .level(Level::Debug)
1697 .target(target)
1698 .build();
1699 assert_eq!(metadata_test.level(), Level::Debug);
1700 assert_eq!(metadata_test.target(), "myApp");
1701 }
1702
1703 #[test]
1704 fn test_record_builder() {
1705 use super::{MetadataBuilder, RecordBuilder};
1706 let target = "myApp";
1707 let metadata = MetadataBuilder::new().target(target).build();
1708 let fmt_args = format_args!("hello");
1709 let record_test = RecordBuilder::new()
1710 .args(fmt_args)
1711 .metadata(metadata)
1712 .module_path(Some("foo"))
1713 .file(Some("bar"))
1714 .line(Some(30))
1715 .build();
1716 assert_eq!(record_test.metadata().target(), "myApp");
1717 assert_eq!(record_test.module_path(), Some("foo"));
1718 assert_eq!(record_test.file(), Some("bar"));
1719 assert_eq!(record_test.line(), Some(30));
1720 }
1721
1722 #[test]
1723 fn test_record_convenience_builder() {
1724 use super::{Metadata, Record};
1725 let target = "myApp";
1726 let metadata = Metadata::builder().target(target).build();
1727 let fmt_args = format_args!("hello");
1728 let record_test = Record::builder()
1729 .args(fmt_args)
1730 .metadata(metadata)
1731 .module_path(Some("foo"))
1732 .file(Some("bar"))
1733 .line(Some(30))
1734 .build();
1735 assert_eq!(record_test.target(), "myApp");
1736 assert_eq!(record_test.module_path(), Some("foo"));
1737 assert_eq!(record_test.file(), Some("bar"));
1738 assert_eq!(record_test.line(), Some(30));
1739 }
1740
1741 #[test]
1742 fn test_record_complete_builder() {
1743 use super::{Level, Record};
1744 let target = "myApp";
1745 let record_test = Record::builder()
1746 .module_path(Some("foo"))
1747 .file(Some("bar"))
1748 .line(Some(30))
1749 .target(target)
1750 .level(Level::Error)
1751 .build();
1752 assert_eq!(record_test.target(), "myApp");
1753 assert_eq!(record_test.level(), Level::Error);
1754 assert_eq!(record_test.module_path(), Some("foo"));
1755 assert_eq!(record_test.file(), Some("bar"));
1756 assert_eq!(record_test.line(), Some(30));
1757 }
1758
1759 #[test]
1760 #[cfg(feature = "kv")]
1761 fn test_record_key_values_builder() {
1762 use super::Record;
1763 use crate::kv::{self, VisitSource};
1764
1765 struct TestVisitSource {
1766 seen_pairs: usize,
1767 }
1768
1769 impl<'kvs> VisitSource<'kvs> for TestVisitSource {
1770 fn visit_pair(
1771 &mut self,
1772 _: kv::Key<'kvs>,
1773 _: kv::Value<'kvs>,
1774 ) -> Result<(), kv::Error> {
1775 self.seen_pairs += 1;
1776 Ok(())
1777 }
1778 }
1779
1780 let kvs: &[(&str, i32)] = &[("a", 1), ("b", 2)];
1781 let record_test = Record::builder().key_values(&kvs).build();
1782
1783 let mut visitor = TestVisitSource { seen_pairs: 0 };
1784
1785 record_test.key_values().visit(&mut visitor).unwrap();
1786
1787 assert_eq!(2, visitor.seen_pairs);
1788 }
1789
1790 #[test]
1791 #[cfg(feature = "kv")]
1792 fn test_record_key_values_get_coerce() {
1793 use super::Record;
1794
1795 let kvs: &[(&str, &str)] = &[("a", "1"), ("b", "2")];
1796 let record = Record::builder().key_values(&kvs).build();
1797
1798 assert_eq!(
1799 "2",
1800 record
1801 .key_values()
1802 .get("b".into())
1803 .expect("missing key")
1804 .to_borrowed_str()
1805 .expect("invalid value")
1806 );
1807 }
1808
1809 // Test that the `impl Log for Foo` blocks work
1810 // This test mostly operates on a type level, so failures will be compile errors
1811 #[test]
1812 fn test_foreign_impl() {
1813 use super::Log;
1814 #[cfg(feature = "std")]
1815 use std::sync::Arc;
1816
1817 fn assert_is_log<T: Log + ?Sized>() {}
1818
1819 assert_is_log::<&dyn Log>();
1820
1821 #[cfg(feature = "std")]
1822 assert_is_log::<Box<dyn Log>>();
1823
1824 #[cfg(feature = "std")]
1825 assert_is_log::<Arc<dyn Log>>();
1826
1827 // Assert these statements for all T: Log + ?Sized
1828 #[allow(unused)]
1829 fn forall<T: Log + ?Sized>() {
1830 #[cfg(feature = "std")]
1831 assert_is_log::<Box<T>>();
1832
1833 assert_is_log::<&T>();
1834
1835 #[cfg(feature = "std")]
1836 assert_is_log::<Arc<T>>();
1837 }
1838 }
1839 }