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