diff options
Diffstat (limited to 'log/index.html')
| -rw-r--r-- | log/index.html | 378 |
1 files changed, 378 insertions, 0 deletions
diff --git a/log/index.html b/log/index.html new file mode 100644 index 0000000..327f216 --- /dev/null +++ b/log/index.html @@ -0,0 +1,378 @@ +<!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="../main.css"> + + <link rel="shortcut icon" href="http://www.rust-lang.org/favicon.ico"> + +</head> +<body class="rustdoc"> + <!--[if lte IE 8]> + <div class="warning"> + This old browser is unsupported and will most likely display funky + things. + </div> + <![endif]--> + + + + <section class="sidebar"> + <a href='../log/index.html'><img src='http://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png' alt='' width='100'></a> + <p class='location'></p><script>window.sidebarCurrent = {name: 'log', ty: 'mod', relpath: '../'};</script> + </section> + + <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 mod"> +<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'>−</span>] + </a> + </span><a id='src-0' class='srclink' href='../src/log/lib.rs.html#11-773' 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 "noop" +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'>&</span><span class='ident'>Yak</span>) { + <span class='macro'>info</span><span class='macro'>!</span>(<span class='ident'>target</span>: <span class='string'>"yak_events"</span>, <span class='string'>"Commencing yak shaving for {:?}"</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'>=></span> { + <span class='macro'>info</span><span class='macro'>!</span>(<span class='string'>"Razor located: {}"</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'>=></span> { + <span class='macro'>warn</span><span class='macro'>!</span>(<span class='string'>"Unable to locate a razor: {}, retrying"</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 chose 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><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'>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'>"starting up"</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'>&</span><span class='self'>self</span>, <span class='ident'>metadata</span>: <span class='kw-2'>&</span><span class='ident'>LogMetadata</span>) <span class='op'>-></span> <span class='ident'>bool</span> { + <span class='ident'>metadata</span>.<span class='ident'>level</span>() <span class='op'><=</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'>&</span><span class='self'>self</span>, <span class='ident'>record</span>: <span class='kw-2'>&</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'>"{} - {}"</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'>-></span> <span class='prelude-ty'>Result</span><span class='op'><</span>(), <span class='ident'>SetLoggerError</span><span class='op'>></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> +</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='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='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='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='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='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='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='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='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='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='log::LogRecord'>LogRecord</a></td> + <td class='docblock short'> + <p>The "payload" of a log message.</p> + + </td> + </tr> + + <tr class=' module-item'> + <td><a class='struct' href='struct.MaxLogLevelFilter.html' + title='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='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> + </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='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='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='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='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='log::set_logger'>set_logger</a></td> + <td class='docblock short'> + <p>Sets the global logger.</p> + + </td> + </tr> + </table></section> + <section id='search' class="content hidden"></section> + + <section class="footer"></section> + + <div id="help" class="hidden"> + <div class="shortcuts"> + <h1>Keyboard shortcuts</h1> + <dl> + <dt>?</dt> + <dd>Show this help dialog</dd> + <dt>S</dt> + <dd>Focus the search field</dd> + <dt>⇤</dt> + <dd>Move up in search results</dd> + <dt>⇥</dt> + <dd>Move down in search results</dd> + <dt>⏎</dt> + <dd>Go to active search result</dd> + </dl> + </div> + <div class="infos"> + <h1>Search tricks</h1> + <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>typedef</code> (or + <code>tdef</code>). + </p> + <p> + Search functions by type signature (e.g. + <code>vec -> usize</code>) + </p> + </div> + </div> + + + + <script> + window.rootPath = "../"; + window.currentCrate = "log"; + window.playgroundUrl = ""; + </script> + <script src="../jquery.js"></script> + <script src="../main.js"></script> + + <script async src="../search-index.js"></script> +</body> +</html>
\ No newline at end of file |