lib.rs source code [crates/log/src/lib.rs]

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