mentat/log/index.html

426 lines
24 KiB
HTML
Raw Permalink Normal View History

2018-08-22 17:04:13 +00:00
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="rustdoc">
<meta name="description" content="API documentation for the Rust `log` crate.">
<meta name="keywords" content="rust, rustlang, rust-lang, log">
<title>log - Rust</title>
<link rel="stylesheet" type="text/css" href="../normalize.css">
<link rel="stylesheet" type="text/css" href="../rustdoc.css" id="mainThemeStyle">
<link rel="stylesheet" type="text/css" href="../dark.css">
<link rel="stylesheet" type="text/css" href="../main.css" id="themeStyle">
<script src="../storage.js"></script>
<link rel="shortcut icon" href="https://www.rust-lang.org/favicon.ico">
</head>
<body class="rustdoc mod">
<!--[if lte IE 8]>
<div class="warning">
This old browser is unsupported and will most likely display funky
things.
</div>
<![endif]-->
<nav class="sidebar">
<div class="sidebar-menu">&#9776;</div>
<a href='../log/index.html'><img src='https://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png' alt='logo' width='100'></a>
<p class='location'>Crate log</p><div class="sidebar-elems"><div class="block items"><ul><li><a href="#macros">Macros</a></li><li><a href="#structs">Structs</a></li><li><a href="#enums">Enums</a></li><li><a href="#traits">Traits</a></li><li><a href="#functions">Functions</a></li></ul></div><p class='location'></p><script>window.sidebarCurrent = {name: 'log', ty: 'mod', relpath: '../'};</script></div>
</nav>
<div class="theme-picker">
<button id="theme-picker" aria-label="Pick another theme!">
<img src="../brush.svg" width="18" alt="Pick another theme!">
</button>
<div id="theme-choices"></div>
</div>
<script src="../theme.js"></script>
<nav class="sub">
<form class="search-form js-only">
<div class="search-container">
<input class="search-input" name="search"
autocomplete="off"
placeholder="Click or press S to search, ? for more options…"
type="search">
</div>
</form>
</nav>
<section id='main' class="content">
<h1 class='fqn'><span class='in-band'>Crate <a class="mod" href=''>log</a></span><span class='out-of-band'><span id='render-detail'>
<a id="toggle-all-docs" href="javascript:void(0)" title="collapse all docs">
[<span class='inner'>&#x2212;</span>]
</a>
</span><a class='srclink' href='../src/log/lib.rs.html#11-1091' title='goto source code'>[src]</a></span></h1>
<div class='docblock'><p>A lightweight logging facade.</p>
<p>A logging facade provides a single logging API that abstracts over the
actual logging implementation. Libraries can use the logging API provided
by this crate, and the consumer of those libraries can choose the logging
framework that is most suitable for its use case.</p>
<p>If no logging implementation is selected, the facade falls back to a &quot;noop&quot;
implementation that ignores all log messages. The overhead in this case
is very small - just an integer load, comparison and jump.</p>
<p>A log request consists of a target, a level, and a body. A target is a
string which defaults to the module path of the location of the log
request, though that default may be overridden. Logger implementations
typically use the target to filter requests based on some user
configuration.</p>
<h1 id="use" class="section-header"><a href="#use">Use</a></h1><h2 id="in-libraries" class="section-header"><a href="#in-libraries">In libraries</a></h2>
<p>Libraries should link only to the <code>log</code> crate, and use the provided
macros to log whatever information will be useful to downstream consumers.</p>
<h3 id="examples" class="section-header"><a href="#examples">Examples</a></h3>
<pre class="rust rust-example-rendered">
<span class="attribute">#[<span class="ident">macro_use</span>]</span>
<span class="kw">extern</span> <span class="kw">crate</span> <span class="ident">log</span>;
<span class="kw">pub</span> <span class="kw">fn</span> <span class="ident">shave_the_yak</span>(<span class="ident">yak</span>: <span class="kw-2">&amp;</span><span class="ident">Yak</span>) {
<span class="macro">info</span><span class="macro">!</span>(<span class="ident">target</span>: <span class="string">&quot;yak_events&quot;</span>, <span class="string">&quot;Commencing yak shaving for {:?}&quot;</span>, <span class="ident">yak</span>);
<span class="kw">loop</span> {
<span class="kw">match</span> <span class="ident">find_a_razor</span>() {
<span class="prelude-val">Ok</span>(<span class="ident">razor</span>) <span class="op">=&gt;</span> {
<span class="macro">info</span><span class="macro">!</span>(<span class="string">&quot;Razor located: {}&quot;</span>, <span class="ident">razor</span>);
<span class="ident">yak</span>.<span class="ident">shave</span>(<span class="ident">razor</span>);
<span class="kw">break</span>;
}
<span class="prelude-val">Err</span>(<span class="ident">err</span>) <span class="op">=&gt;</span> {
<span class="macro">warn</span><span class="macro">!</span>(<span class="string">&quot;Unable to locate a razor: {}, retrying&quot;</span>, <span class="ident">err</span>);
}
}
}
}</pre>
<h2 id="in-executables" class="section-header"><a href="#in-executables">In executables</a></h2>
<p>Executables should choose a logging framework and initialize it early in the
runtime of the program. Logging frameworks will typically include a
function to do this. Any log messages generated before the framework is
initialized will be ignored.</p>
<p>The executable itself may use the <code>log</code> crate to log as well.</p>
<h3 id="warning" class="section-header"><a href="#warning">Warning</a></h3>
<p>The logging system may only be initialized once.</p>
<h3 id="examples-1" class="section-header"><a href="#examples-1">Examples</a></h3>
<div class='information'><div class='tooltip ignore'><span class='tooltiptext'>This example is not tested</span></div></div><pre class="rust rust-example-rendered ignore">
<span class="attribute">#[<span class="ident">macro_use</span>]</span>
<span class="kw">extern</span> <span class="kw">crate</span> <span class="ident">log</span>;
<span class="kw">extern</span> <span class="kw">crate</span> <span class="ident">my_logger</span>;
<span class="kw">fn</span> <span class="ident">main</span>() {
<span class="ident">my_logger</span>::<span class="ident">init</span>();
<span class="macro">info</span><span class="macro">!</span>(<span class="string">&quot;starting up&quot;</span>);
<span class="comment">// ...</span>
}</pre>
<h1 id="logger-implementations" class="section-header"><a href="#logger-implementations">Logger implementations</a></h1>
<p>Loggers implement the <code>Log</code> trait. Here's a very basic example that simply
logs all messages at the <code>Error</code>, <code>Warn</code> or <code>Info</code> levels to stdout:</p>
<pre class="rust rust-example-rendered">
<span class="kw">extern</span> <span class="kw">crate</span> <span class="ident">log</span>;
<span class="kw">use</span> <span class="ident">log</span>::{<span class="ident">LogRecord</span>, <span class="ident">LogLevel</span>, <span class="ident">LogMetadata</span>};
<span class="kw">struct</span> <span class="ident">SimpleLogger</span>;
<span class="kw">impl</span> <span class="ident">log</span>::<span class="ident">Log</span> <span class="kw">for</span> <span class="ident">SimpleLogger</span> {
<span class="kw">fn</span> <span class="ident">enabled</span>(<span class="kw-2">&amp;</span><span class="self">self</span>, <span class="ident">metadata</span>: <span class="kw-2">&amp;</span><span class="ident">LogMetadata</span>) <span class="op">-&gt;</span> <span class="ident">bool</span> {
<span class="ident">metadata</span>.<span class="ident">level</span>() <span class="op">&lt;=</span> <span class="ident">LogLevel</span>::<span class="ident">Info</span>
}
<span class="kw">fn</span> <span class="ident">log</span>(<span class="kw-2">&amp;</span><span class="self">self</span>, <span class="ident">record</span>: <span class="kw-2">&amp;</span><span class="ident">LogRecord</span>) {
<span class="kw">if</span> <span class="self">self</span>.<span class="ident">enabled</span>(<span class="ident">record</span>.<span class="ident">metadata</span>()) {
<span class="macro">println</span><span class="macro">!</span>(<span class="string">&quot;{} - {}&quot;</span>, <span class="ident">record</span>.<span class="ident">level</span>(), <span class="ident">record</span>.<span class="ident">args</span>());
}
}
}
</pre>
<p>Loggers are installed by calling the <code>set_logger</code> function. It takes a
closure which is provided a <code>MaxLogLevel</code> token and returns a <code>Log</code> trait
object. The <code>MaxLogLevel</code> token controls the global maximum log level. The
logging facade uses this as an optimization to improve performance of log
messages at levels that are disabled. In the case of our example logger,
we'll want to set the maximum log level to <code>Info</code>, since we ignore any
<code>Debug</code> or <code>Trace</code> level log messages. A logging framework should provide a
function that wraps a call to <code>set_logger</code>, handling initialization of the
logger:</p>
<pre class="rust rust-example-rendered">
<span class="kw">pub</span> <span class="kw">fn</span> <span class="ident">init</span>() <span class="op">-&gt;</span> <span class="prelude-ty">Result</span><span class="op">&lt;</span>(), <span class="ident">SetLoggerError</span><span class="op">&gt;</span> {
<span class="ident">log</span>::<span class="ident">set_logger</span>(<span class="op">|</span><span class="ident">max_log_level</span><span class="op">|</span> {
<span class="ident">max_log_level</span>.<span class="ident">set</span>(<span class="ident">LogLevelFilter</span>::<span class="ident">Info</span>);
<span class="ident">Box</span>::<span class="ident">new</span>(<span class="ident">SimpleLogger</span>)
})
}</pre>
<h1 id="use-with-no_std" class="section-header"><a href="#use-with-no_std">Use with <code>no_std</code></a></h1>
<p>To use the <code>log</code> crate without depending on <code>libstd</code>, you need to specify
<code>default-features = false</code> when specifying the dependency in <code>Cargo.toml</code>.
This makes no difference to libraries using <code>log</code> since the logging API
remains the same. However executables will need to use the <code>set_logger_raw</code>
function to initialize a logger and the <code>shutdown_logger_raw</code> function to
shut down the global logger before exiting:</p>
<pre class="rust rust-example-rendered">
<span class="kw">pub</span> <span class="kw">fn</span> <span class="ident">init</span>() <span class="op">-&gt;</span> <span class="prelude-ty">Result</span><span class="op">&lt;</span>(), <span class="ident">SetLoggerError</span><span class="op">&gt;</span> {
<span class="kw">unsafe</span> {
<span class="ident">log</span>::<span class="ident">set_logger_raw</span>(<span class="op">|</span><span class="ident">max_log_level</span><span class="op">|</span> {
<span class="kw">static</span> <span class="ident">LOGGER</span>: <span class="ident">SimpleLogger</span> <span class="op">=</span> <span class="ident">SimpleLogger</span>;
<span class="ident">max_log_level</span>.<span class="ident">set</span>(<span class="ident">LogLevelFilter</span>::<span class="ident">Info</span>);
<span class="kw-2">&amp;</span><span class="ident">SimpleLogger</span>
})
}
}
<span class="kw">pub</span> <span class="kw">fn</span> <span class="ident">shutdown</span>() <span class="op">-&gt;</span> <span class="prelude-ty">Result</span><span class="op">&lt;</span>(), <span class="ident">ShutdownLoggerError</span><span class="op">&gt;</span> {
<span class="ident">log</span>::<span class="ident">shutdown_logger_raw</span>().<span class="ident">map</span>(<span class="op">|</span><span class="ident">logger</span><span class="op">|</span> {
<span class="kw">let</span> <span class="ident">logger</span> <span class="op">=</span> <span class="kw">unsafe</span> { <span class="kw-2">&amp;</span><span class="kw-2">*</span>(<span class="ident">logger</span> <span class="kw">as</span> <span class="kw-2">*</span><span class="kw">const</span> <span class="ident">SimpleLogger</span>) };
<span class="ident">logger</span>.<span class="ident">flush</span>();
})
}</pre>
</div><h2 id='macros' class='section-header'><a href="#macros">Macros</a></h2>
<table>
<tr class=' module-item'>
<td><a class="macro" href="macro.debug.html"
title='macro log::debug'>debug</a></td>
<td class='docblock-short'>
<p>Logs a message at the debug level.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="macro" href="macro.error.html"
title='macro log::error'>error</a></td>
<td class='docblock-short'>
<p>Logs a message at the error level.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="macro" href="macro.info.html"
title='macro log::info'>info</a></td>
<td class='docblock-short'>
<p>Logs a message at the info level.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="macro" href="macro.log.html"
title='macro log::log'>log</a></td>
<td class='docblock-short'>
<p>The standard logging macro.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="macro" href="macro.log_enabled.html"
title='macro log::log_enabled'>log_enabled</a></td>
<td class='docblock-short'>
<p>Determines if a message logged at the specified level in that module will
be logged.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="macro" href="macro.trace.html"
title='macro log::trace'>trace</a></td>
<td class='docblock-short'>
<p>Logs a message at the trace level.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="macro" href="macro.warn.html"
title='macro log::warn'>warn</a></td>
<td class='docblock-short'>
<p>Logs a message at the warn level.</p>
</td>
</tr></table><h2 id='structs' class='section-header'><a href="#structs">Structs</a></h2>
<table>
<tr class=' module-item'>
<td><a class="struct" href="struct.LogLocation.html"
title='struct log::LogLocation'>LogLocation</a></td>
<td class='docblock-short'>
<p>The location of a log message.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="struct" href="struct.LogMetadata.html"
title='struct log::LogMetadata'>LogMetadata</a></td>
<td class='docblock-short'>
<p>Metadata about a log message.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="struct" href="struct.LogRecord.html"
title='struct log::LogRecord'>LogRecord</a></td>
<td class='docblock-short'>
<p>The &quot;payload&quot; of a log message.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="struct" href="struct.MaxLogLevelFilter.html"
title='struct log::MaxLogLevelFilter'>MaxLogLevelFilter</a></td>
<td class='docblock-short'>
<p>A token providing read and write access to the global maximum log level
filter.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="struct" href="struct.SetLoggerError.html"
title='struct log::SetLoggerError'>SetLoggerError</a></td>
<td class='docblock-short'>
<p>The type returned by <code>set_logger</code> if <code>set_logger</code> has already been called.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="struct" href="struct.ShutdownLoggerError.html"
title='struct log::ShutdownLoggerError'>ShutdownLoggerError</a></td>
<td class='docblock-short'>
<p>The type returned by <code>shutdown_logger_raw</code> if <code>shutdown_logger_raw</code> has
already been called or if <code>set_logger_raw</code> has not been called yet.</p>
</td>
</tr></table><h2 id='enums' class='section-header'><a href="#enums">Enums</a></h2>
<table>
<tr class=' module-item'>
<td><a class="enum" href="enum.LogLevel.html"
title='enum log::LogLevel'>LogLevel</a></td>
<td class='docblock-short'>
<p>An enum representing the available verbosity levels of the logging framework</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="enum" href="enum.LogLevelFilter.html"
title='enum log::LogLevelFilter'>LogLevelFilter</a></td>
<td class='docblock-short'>
<p>An enum representing the available verbosity level filters of the logging
framework.</p>
</td>
</tr></table><h2 id='traits' class='section-header'><a href="#traits">Traits</a></h2>
<table>
<tr class=' module-item'>
<td><a class="trait" href="trait.Log.html"
title='trait log::Log'>Log</a></td>
<td class='docblock-short'>
<p>A trait encapsulating the operations required of a logger</p>
</td>
</tr></table><h2 id='functions' class='section-header'><a href="#functions">Functions</a></h2>
<table>
<tr class=' module-item'>
<td><a class="fn" href="fn.max_log_level.html"
title='fn log::max_log_level'>max_log_level</a></td>
<td class='docblock-short'>
<p>Returns the current maximum log level.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="fn" href="fn.set_logger.html"
title='fn log::set_logger'>set_logger</a></td>
<td class='docblock-short'>
<p>Sets the global logger.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="fn" href="fn.set_logger_raw.html"
title='fn log::set_logger_raw'>set_logger_raw</a><a title='unsafe function' href='#'><sup></sup></a></td>
<td class='docblock-short'>
<p>Sets the global logger from a raw pointer.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="fn" href="fn.shutdown_logger.html"
title='fn log::shutdown_logger'>shutdown_logger</a></td>
<td class='docblock-short'>
<p>Shuts down the global logger.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="fn" href="fn.shutdown_logger_raw.html"
title='fn log::shutdown_logger_raw'>shutdown_logger_raw</a></td>
<td class='docblock-short'>
<p>Shuts down the global logger.</p>
</td>
</tr></table></section>
<section id='search' class="content hidden"></section>
<section class="footer"></section>
<aside id="help" class="hidden">
<div>
<h1 class="hidden">Help</h1>
<div class="shortcuts">
<h2>Keyboard Shortcuts</h2>
<dl>
<dt><kbd>?</kbd></dt>
<dd>Show this help dialog</dd>
<dt><kbd>S</kbd></dt>
<dd>Focus the search field</dd>
<dt><kbd></kbd></dt>
<dd>Move up in search results</dd>
<dt><kbd></kbd></dt>
<dd>Move down in search results</dd>
<dt><kbd></kbd></dt>
<dd>Switch tab</dd>
<dt><kbd>&#9166;</kbd></dt>
<dd>Go to active search result</dd>
<dt><kbd>+</kbd></dt>
<dd>Expand all sections</dd>
<dt><kbd>-</kbd></dt>
<dd>Collapse all sections</dd>
</dl>
</div>
<div class="infos">
<h2>Search Tricks</h2>
<p>
Prefix searches with a type followed by a colon (e.g.
<code>fn:</code>) to restrict the search to a given type.
</p>
<p>
Accepted types are: <code>fn</code>, <code>mod</code>,
<code>struct</code>, <code>enum</code>,
<code>trait</code>, <code>type</code>, <code>macro</code>,
and <code>const</code>.
</p>
<p>
Search functions by type signature (e.g.
<code>vec -> usize</code> or <code>* -> vec</code>)
</p>
</div>
</div>
</aside>
<script>
window.rootPath = "../";
window.currentCrate = "log";
</script>
<script src="../main.js"></script>
<script defer src="../search-index.js"></script>
</body>
</html>