lib.rs source code [crates/log-0.4.21/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	//! ## 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(err: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(err: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: &str) => s,
669	MaybeStaticStr::Borrowed(s: &str) => 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(val:level as usize, order: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(val:level as usize, order: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(src:MAX_LOG_LEVEL_FILTER.load(order: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(order:Ordering::SeqCst) {
1409	UNINITIALIZED => {
1410	LOGGER = logger;
1411	STATE.store(INITIALIZED, order: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(data: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(data: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(order: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	}
1840