libs/log/doc/html/log/detailed/utilities.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Utilities</title>
   5 <link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css">
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
   7 <link rel="home" href="../../index.html" title="Chapter&#160;1.&#160;Boost.Log v2">
   8 <link rel="up" href="../detailed.html" title="Detailed features description">
   9 <link rel="prev" href="attributes.html" title="Attributes">
  10 <link rel="next" href="../extension.html" title="Extending the library">
  11 </head>
  12 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  13 <table cellpadding="2" width="100%"><tr><td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td></tr></table>
  14 <hr>
  15 <div class="spirit-nav">
  16 <a accesskey="p" href="attributes.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../detailed.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../extension.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
  17 </div>
  18 <div class="section">
  19 <div class="titlepage"><div><div><h3 class="title">
  20 <a name="log.detailed.utilities"></a><a class="link" href="utilities.html" title="Utilities">Utilities</a>
  21 </h3></div></div></div>
  22 <div class="toc"><dl class="toc">
  23 <dt><span class="section"><a href="utilities.html#log.detailed.utilities.string_literal">String literals</a></span></dt>
  24 <dt><span class="section"><a href="utilities.html#log.detailed.utilities.type_dispatch">Type dispatchers</a></span></dt>
  25 <dt><span class="section"><a href="utilities.html#log.detailed.utilities.predef_types">Predefined type
  26         sequences</a></span></dt>
  27 <dt><span class="section"><a href="utilities.html#log.detailed.utilities.value_ref">Value reference wrapper</a></span></dt>
  28 <dt><span class="section"><a href="utilities.html#log.detailed.utilities.record_ordering">Log record
  29         ordering</a></span></dt>
  30 <dt><span class="section"><a href="utilities.html#log.detailed.utilities.exception_handlers">Exception
  31         handlers</a></span></dt>
  32 <dt><span class="section"><a href="utilities.html#log.detailed.utilities.manipulators">Output manipulators</a></span></dt>
  33 <dt><span class="section"><a href="utilities.html#log.detailed.utilities.ipc">Interprocess communication
  34         tools</a></span></dt>
  35 <dt><span class="section"><a href="utilities.html#log.detailed.utilities.setup">Simplified library initialization
  36         tools</a></span></dt>
  37 </dl></div>
  38 <div class="section">
  39 <div class="titlepage"><div><div><h4 class="title">
  40 <a name="log.detailed.utilities.string_literal"></a><a class="link" href="utilities.html#log.detailed.utilities.string_literal" title="String literals">String literals</a>
  41 </h4></div></div></div>
  42 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><code class="computeroutput"><a class="link" href="../../utilities.html#header.boost.log.utility.string_literal_hpp" title="Header &lt;boost/log/utility/string_literal.hpp&gt;">boost/log/utility/string_literal.hpp</a></code><span class="special">&gt;</span>
  43 </pre>
  44 <p>
  45           String literals are used in several places throughout the library. However,
  46           this component can be successfully used outside of the library in users'
  47           code. It is header-only and does not require linking with the library binary.
  48           String literals can improve performance significantly if there is no need
  49           to modify stored strings. What is also important, since string literals
  50           do not dynamically allocate memory, it is easier to maintain exception
  51           safety when using string literals instead of regular strings.
  52         </p>
  53 <p>
  54           The functionality is implemented in the <code class="computeroutput"><a class="link" href="../../boost/log/basic_string_literal.html" title="Class template basic_string_literal">basic_string_literal</a></code>
  55           class template, which is parametrized with the character and character
  56           traits, similar to <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">basic_string</span></code>.
  57           There are also two convenience typedefs provided: <code class="computeroutput"><span class="identifier">string_literal</span></code>
  58           and <code class="computeroutput"><span class="identifier">wstring_literal</span></code>, for
  59           narrow and wide character types, respectively. In order to ease string
  60           literal construction in generic code there is also a <code class="computeroutput"><span class="identifier">str_literal</span></code>
  61           function template that accepts a string literal and returns a <code class="computeroutput"><a class="link" href="../../boost/log/basic_string_literal.html" title="Class template basic_string_literal">basic_string_literal</a></code>
  62           instance for the appropriate character type.
  63         </p>
  64 <p>
  65           String literals support interface similar to STL strings, except for string
  66           modification functions. However, it is possible to assign to or clear string
  67           literals, as long as only string literals involved. Relational and stream
  68           output operators are also supported.
  69         </p>
  70 </div>
  71 <div class="section">
  72 <div class="titlepage"><div><div><h4 class="title">
  73 <a name="log.detailed.utilities.type_dispatch"></a><a class="link" href="utilities.html#log.detailed.utilities.type_dispatch" title="Type dispatchers">Type dispatchers</a>
  74 </h4></div></div></div>
  75 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><code class="computeroutput"><a class="link" href="../../utilities.html#header.boost.log.utility.type_dispatch.type_dispatcher_hpp" title="Header &lt;boost/log/utility/type_dispatch/type_dispatcher.hpp&gt;">boost/log/utility/type_dispatch/type_dispatcher.hpp</a></code><span class="special">&gt;</span>
  76 </pre>
  77 <p>
  78           Type dispatchers are used throughout the library in order to work with
  79           attribute values. Dispatchers allow acquiring the stored attribute value
  80           using the Visitor concept. The most notable places where the functionality
  81           is used are filters and formatters. However, this mechanism is orthogonal
  82           to attributes and can be used for other purposes as well. Most of the time
  83           users won't need to dig into the details of type dispatchers, but this
  84           information may be useful for those who intend to extend the library and
  85           wants to understand what's under the hood.
  86         </p>
  87 <p>
  88           Every type dispatcher supports the <code class="computeroutput"><a class="link" href="../../boost/log/type_dispatcher.html" title="Class type_dispatcher">type_dispatcher</a></code>
  89           interface. When an attribute value needs to be extracted, this interface
  90           is passed to the attribute value object, which then tries to acquire the
  91           callback for the actual type of the value. All callbacks are objects of
  92           the [class_type_dispatcher_callback] class template, instantiated on the
  93           actual type of the value. If the dispatcher is able to consume the value
  94           of the requested type, it must return a non-empty callback object. When
  95           (and if) the corresponding callback is acquired, the attribute value object
  96           only has to pass the contained value to its <code class="computeroutput"><span class="keyword">operator</span>
  97           <span class="special">()</span></code>.
  98         </p>
  99 <p>
 100           Happily, there is no need to write type dispatchers from scratch. The library
 101           provides two kinds of type dispatchers that implement the <code class="computeroutput"><a class="link" href="../../boost/log/type_dispatcher.html" title="Class type_dispatcher">type_dispatcher</a></code>
 102           and [class_type_dispatcher_callback] interfaces and encapsulate the callback
 103           lookup.
 104         </p>
 105 <h6>
 106 <a name="log.detailed.utilities.type_dispatch.h0"></a>
 107           <span class="phrase"><a name="log.detailed.utilities.type_dispatch.static_type_dispatcher"></a></span><a class="link" href="utilities.html#log.detailed.utilities.type_dispatch.static_type_dispatcher">Static
 108           type dispatcher</a>
 109         </h6>
 110 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><code class="computeroutput"><a class="link" href="../../utilities.html#header.boost.log.utility.type_dispatch.static_type_dispatcher_hpp" title="Header &lt;boost/log/utility/type_dispatch/static_type_dispatcher.hpp&gt;">boost/log/utility/type_dispatch/static_type_dispatcher.hpp</a></code><span class="special">&gt;</span>
 111 </pre>
 112 <p>
 113           Static type dispatchers are used when the set of types that needs to be
 114           supported for extraction is known at compile time. The <code class="computeroutput"><a class="link" href="../../boost/log/static_type_dispatcher.html" title="Class template static_type_dispatcher">static_type_dispatcher</a></code>
 115           class template is parametrized with an MPL type sequence of types that
 116           need to be supported. The dispatcher inherits from the <code class="computeroutput"><a class="link" href="../../boost/log/type_dispatcher.html" title="Class type_dispatcher">type_dispatcher</a></code>
 117           interface which provides the <code class="computeroutput"><span class="identifier">get_callback</span></code>
 118           method for acquiring the function object to invoke on the stored value.
 119           All you need to do is provide a visitor function object to the dispatcher
 120           at construction point and invoke the callback when dispatching the stored
 121           value:
 122         </p>
 123 <p>
 124 </p>
 125 <pre class="programlisting"><span class="comment">// Base interface for the custom opaque value</span>
 126 <span class="keyword">struct</span> <span class="identifier">my_value_base</span>
 127 <span class="special">{</span>
 128     <span class="keyword">virtual</span> <span class="special">~</span><span class="identifier">my_value_base</span><span class="special">()</span> <span class="special">{}</span>
 129     <span class="keyword">virtual</span> <span class="keyword">bool</span> <span class="identifier">dispatch</span><span class="special">(</span><span class="identifier">logging</span><span class="special">::</span><span class="identifier">type_dispatcher</span><span class="special">&amp;</span> <span class="identifier">dispatcher</span><span class="special">)</span> <span class="keyword">const</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span>
 130 <span class="special">};</span>
 131
 132 <span class="comment">// A simple attribute value</span>
 133 <span class="keyword">template</span><span class="special">&lt;</span> <span class="keyword">typename</span> <span class="identifier">T</span> <span class="special">&gt;</span>
 134 <span class="keyword">struct</span> <span class="identifier">my_value</span> <span class="special">:</span>
 135     <span class="keyword">public</span> <span class="identifier">my_value_base</span>
 136 <span class="special">{</span>
 137     <span class="identifier">T</span> <span class="identifier">m_value</span><span class="special">;</span>
 138
 139     <span class="keyword">explicit</span> <span class="identifier">my_value</span><span class="special">(</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">value</span><span class="special">)</span> <span class="special">:</span> <span class="identifier">m_value</span><span class="special">(</span><span class="identifier">value</span><span class="special">)</span> <span class="special">{}</span>
 140
 141     <span class="comment">// The function passes the contained type into the dispatcher</span>
 142     <span class="keyword">bool</span> <span class="identifier">dispatch</span><span class="special">(</span><span class="identifier">logging</span><span class="special">::</span><span class="identifier">type_dispatcher</span><span class="special">&amp;</span> <span class="identifier">dispatcher</span><span class="special">)</span> <span class="keyword">const</span>
 143     <span class="special">{</span>
 144         <span class="identifier">logging</span><span class="special">::</span><span class="identifier">type_dispatcher</span><span class="special">::</span><span class="identifier">callback</span><span class="special">&lt;</span> <span class="identifier">T</span> <span class="special">&gt;</span> <span class="identifier">cb</span> <span class="special">=</span> <span class="identifier">dispatcher</span><span class="special">.</span><span class="identifier">get_callback</span><span class="special">&lt;</span> <span class="identifier">T</span> <span class="special">&gt;();</span>
 145         <span class="keyword">if</span> <span class="special">(</span><span class="identifier">cb</span><span class="special">)</span>
 146         <span class="special">{</span>
 147             <span class="identifier">cb</span><span class="special">(</span><span class="identifier">m_value</span><span class="special">);</span>
 148             <span class="keyword">return</span> <span class="keyword">true</span><span class="special">;</span>
 149         <span class="special">}</span>
 150         <span class="keyword">else</span>
 151             <span class="keyword">return</span> <span class="keyword">false</span><span class="special">;</span>
 152     <span class="special">}</span>
 153 <span class="special">};</span>
 154
 155 <span class="comment">// Value visitor for the supported types</span>
 156 <span class="keyword">struct</span> <span class="identifier">print_visitor</span>
 157 <span class="special">{</span>
 158     <span class="keyword">typedef</span> <span class="keyword">void</span> <span class="identifier">result_type</span><span class="special">;</span>
 159
 160     <span class="comment">// Implement visitation logic for all supported types</span>
 161     <span class="keyword">void</span> <span class="keyword">operator</span><span class="special">()</span> <span class="special">(</span><span class="keyword">int</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">value</span><span class="special">)</span> <span class="keyword">const</span>
 162     <span class="special">{</span>
 163         <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Received int value = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">value</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
 164     <span class="special">}</span>
 165     <span class="keyword">void</span> <span class="keyword">operator</span><span class="special">()</span> <span class="special">(</span><span class="keyword">double</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">value</span><span class="special">)</span> <span class="keyword">const</span>
 166     <span class="special">{</span>
 167         <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Received double value = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">value</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
 168     <span class="special">}</span>
 169     <span class="keyword">void</span> <span class="keyword">operator</span><span class="special">()</span> <span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">value</span><span class="special">)</span> <span class="keyword">const</span>
 170     <span class="special">{</span>
 171         <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Received string value = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">value</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
 172     <span class="special">}</span>
 173 <span class="special">};</span>
 174
 175 <span class="comment">// Prints the supplied value</span>
 176 <span class="keyword">bool</span> <span class="identifier">print</span><span class="special">(</span><span class="identifier">my_value_base</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">val</span><span class="special">)</span>
 177 <span class="special">{</span>
 178     <span class="keyword">typedef</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">mpl</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span> <span class="keyword">int</span><span class="special">,</span> <span class="keyword">double</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="special">&gt;</span> <span class="identifier">types</span><span class="special">;</span>
 179
 180     <span class="identifier">print_visitor</span> <span class="identifier">visitor</span><span class="special">;</span>
 181     <span class="identifier">logging</span><span class="special">::</span><span class="identifier">static_type_dispatcher</span><span class="special">&lt;</span> <span class="identifier">types</span> <span class="special">&gt;</span> <span class="identifier">disp</span><span class="special">(</span><span class="identifier">visitor</span><span class="special">);</span>
 182
 183     <span class="keyword">return</span> <span class="identifier">val</span><span class="special">.</span><span class="identifier">dispatch</span><span class="special">(</span><span class="identifier">disp</span><span class="special">);</span>
 184 <span class="special">}</span>
 185 </pre>
 186 <p>
 187         </p>
 188 <p>
 189           <a href="../../../../../../libs/log/example/doc/util_static_type_disp.cpp" target="_top">See
 190           the complete code</a>.
 191         </p>
 192 <h6>
 193 <a name="log.detailed.utilities.type_dispatch.h1"></a>
 194           <span class="phrase"><a name="log.detailed.utilities.type_dispatch.dynamic_type_dispatcher"></a></span><a class="link" href="utilities.html#log.detailed.utilities.type_dispatch.dynamic_type_dispatcher">Dynamic
 195           type dispatcher</a>
 196         </h6>
 197 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><code class="computeroutput"><a class="link" href="../../utilities.html#header.boost.log.utility.type_dispatch.dynamic_type_dispatcher_hpp" title="Header &lt;boost/log/utility/type_dispatch/dynamic_type_dispatcher.hpp&gt;">boost/log/utility/type_dispatch/dynamic_type_dispatcher.hpp</a></code><span class="special">&gt;</span>
 198 </pre>
 199 <p>
 200           If the set of types that have to be supported is not available at compile
 201           time, the <code class="computeroutput"><a class="link" href="../../boost/log/dynamic_type_dispatcher.html" title="Class dynamic_type_dispatcher">dynamic_type_dispatcher</a></code>
 202           class is there to help. One can use its <code class="computeroutput"><span class="identifier">register_type</span></code>
 203           method to add support for a particular type. The user has to pass a function
 204           object along with the type, this functor will be called when a visitor
 205           for the specified type is invoked. Considering the <code class="computeroutput"><span class="identifier">my_value</span></code>
 206           from the code sample for static type dispatcher is intact, the code can
 207           be rewritten as follows:
 208         </p>
 209 <p>
 210 </p>
 211 <pre class="programlisting"><span class="comment">// Visitor functions for the supported types</span>
 212 <span class="keyword">void</span> <span class="identifier">on_int</span><span class="special">(</span><span class="keyword">int</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">value</span><span class="special">)</span>
 213 <span class="special">{</span>
 214     <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Received int value = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">value</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
 215 <span class="special">}</span>
 216
 217 <span class="keyword">void</span> <span class="identifier">on_double</span><span class="special">(</span><span class="keyword">double</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">value</span><span class="special">)</span>
 218 <span class="special">{</span>
 219     <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Received double value = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">value</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
 220 <span class="special">}</span>
 221
 222 <span class="keyword">void</span> <span class="identifier">on_string</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">value</span><span class="special">)</span>
 223 <span class="special">{</span>
 224     <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Received string value = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">value</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
 225 <span class="special">}</span>
 226
 227 <span class="identifier">logging</span><span class="special">::</span><span class="identifier">dynamic_type_dispatcher</span> <span class="identifier">disp</span><span class="special">;</span>
 228
 229 <span class="comment">// The function initializes the dispatcher object</span>
 230 <span class="keyword">void</span> <span class="identifier">init_disp</span><span class="special">()</span>
 231 <span class="special">{</span>
 232     <span class="comment">// Register type visitors</span>
 233     <span class="identifier">disp</span><span class="special">.</span><span class="identifier">register_type</span><span class="special">&lt;</span> <span class="keyword">int</span> <span class="special">&gt;(&amp;</span><span class="identifier">on_int</span><span class="special">);</span>
 234     <span class="identifier">disp</span><span class="special">.</span><span class="identifier">register_type</span><span class="special">&lt;</span> <span class="keyword">double</span> <span class="special">&gt;(&amp;</span><span class="identifier">on_double</span><span class="special">);</span>
 235     <span class="identifier">disp</span><span class="special">.</span><span class="identifier">register_type</span><span class="special">&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="special">&gt;(&amp;</span><span class="identifier">on_string</span><span class="special">);</span>
 236 <span class="special">}</span>
 237
 238 <span class="comment">// Prints the supplied value</span>
 239 <span class="keyword">bool</span> <span class="identifier">print</span><span class="special">(</span><span class="identifier">my_value_base</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">val</span><span class="special">)</span>
 240 <span class="special">{</span>
 241     <span class="keyword">return</span> <span class="identifier">val</span><span class="special">.</span><span class="identifier">dispatch</span><span class="special">(</span><span class="identifier">disp</span><span class="special">);</span>
 242 <span class="special">}</span>
 243 </pre>
 244 <p>
 245         </p>
 246 <p>
 247           <a href="../../../../../../libs/log/example/doc/util_dynamic_type_disp.cpp" target="_top">See
 248           the complete code</a>.
 249         </p>
 250 <p>
 251           Of course, complex function objects, like those provided by <a href="http://www.boost.org/doc/libs/release/libs/bind/bind.html" target="_top">Boost.Bind</a>,
 252           are also supported.
 253         </p>
 254 </div>
 255 <div class="section">
 256 <div class="titlepage"><div><div><h4 class="title">
 257 <a name="log.detailed.utilities.predef_types"></a><a class="link" href="utilities.html#log.detailed.utilities.predef_types" title="Predefined type sequences">Predefined type
 258         sequences</a>
 259 </h4></div></div></div>
 260 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><code class="computeroutput"><a class="link" href="../../utilities.html#header.boost.log.utility.type_dispatch.standard_types_hpp" title="Header &lt;boost/log/utility/type_dispatch/standard_types.hpp&gt;">boost/log/utility/type_dispatch/standard_types.hpp</a></code><span class="special">&gt;</span>
 261 <span class="preprocessor">#include</span> <span class="special">&lt;</span><code class="computeroutput"><a class="link" href="../../utilities.html#header.boost.log.utility.type_dispatch.date_time_types_hpp" title="Header &lt;boost/log/utility/type_dispatch/date_time_types.hpp&gt;">boost/log/utility/type_dispatch/date_time_types.hpp</a></code><span class="special">&gt;</span>
 262 </pre>
 263 <p>
 264           One may notice that when using type dispatchers and defining filters and
 265           formatters it may be convenient to have some predefined type sequences
 266           to designate frequently used sets of types. The library provides several
 267           such sets.
 268         </p>
 269 <div class="table">
 270 <a name="log.detailed.utilities.predef_types.standard_types__standard_types_hpp_"></a><p class="title"><b>Table&#160;1.6.&#160;Standard types (standard_types.hpp)</b></p>
 271 <div class="table-contents"><table class="table" summary="Standard types (standard_types.hpp)">
 272 <colgroup>
 273 <col>
 274 <col>
 275 </colgroup>
 276 <thead><tr>
 277 <th>
 278                   <p>
 279                     Type sequence
 280                   </p>
 281                 </th>
 282 <th>
 283                   <p>
 284                     Meaning
 285                   </p>
 286                 </th>
 287 </tr></thead>
 288 <tbody>
 289 <tr>
 290 <td>
 291                   <p>
 292                     <code class="computeroutput"><span class="identifier">integral_types</span></code>
 293                   </p>
 294                 </td>
 295 <td>
 296                   <p>
 297                     All integral types, including <code class="computeroutput"><span class="keyword">bool</span></code>,
 298                     character and 64 bit integral types, if available
 299                   </p>
 300                 </td>
 301 </tr>
 302 <tr>
 303 <td>
 304                   <p>
 305                     <code class="computeroutput"><span class="identifier">floating_point_types</span></code>
 306                   </p>
 307                 </td>
 308 <td>
 309                   <p>
 310                     Floating point types
 311                   </p>
 312                 </td>
 313 </tr>
 314 <tr>
 315 <td>
 316                   <p>
 317                     <code class="computeroutput"><span class="identifier">numeric_types</span></code>
 318                   </p>
 319                 </td>
 320 <td>
 321                   <p>
 322                     Includes <code class="computeroutput"><span class="identifier">integral_types</span></code>
 323                     and <code class="computeroutput"><span class="identifier">floating_point_types</span></code>
 324                   </p>
 325                 </td>
 326 </tr>
 327 <tr>
 328 <td>
 329                   <p>
 330                     <code class="computeroutput"><span class="identifier">string_types</span></code>
 331                   </p>
 332                 </td>
 333 <td>
 334                   <p>
 335                     Narrow and wide string types. Currently only includes STL string
 336                     types and <a class="link" href="utilities.html#log.detailed.utilities.string_literal" title="String literals">string
 337                     literals</a>.
 338                   </p>
 339                 </td>
 340 </tr>
 341 </tbody>
 342 </table></div>
 343 </div>
 344 <br class="table-break"><p>
 345           There are also a number of time-related type sequences available:
 346         </p>
 347 <div class="table">
 348 <a name="log.detailed.utilities.predef_types.time_related_types__date_time_types_hpp_"></a><p class="title"><b>Table&#160;1.7.&#160;Time-related types (date_time_types.hpp)</b></p>
 349 <div class="table-contents"><table class="table" summary="Time-related types (date_time_types.hpp)">
 350 <colgroup>
 351 <col>
 352 <col>
 353 </colgroup>
 354 <thead><tr>
 355 <th>
 356                   <p>
 357                     Type sequence
 358                   </p>
 359                 </th>
 360 <th>
 361                   <p>
 362                     Meaning
 363                   </p>
 364                 </th>
 365 </tr></thead>
 366 <tbody>
 367 <tr>
 368 <td>
 369                   <p>
 370                     <code class="computeroutput"><span class="identifier">native_date_time_types</span></code>
 371                   </p>
 372                 </td>
 373 <td>
 374                   <p>
 375                     All types defined in C/C++ standard that have both date and time
 376                     portions
 377                   </p>
 378                 </td>
 379 </tr>
 380 <tr>
 381 <td>
 382                   <p>
 383                     <code class="computeroutput"><span class="identifier">boost_date_time_types</span></code>
 384                   </p>
 385                 </td>
 386 <td>
 387                   <p>
 388                     All types defined in <a href="http://www.boost.org/doc/libs/release/doc/html/date_time.html" target="_top">Boost.DateTime</a>
 389                     that have both date and time portions
 390                   </p>
 391                 </td>
 392 </tr>
 393 <tr>
 394 <td>
 395                   <p>
 396                     <code class="computeroutput"><span class="identifier">date_time_types</span></code>
 397                   </p>
 398                 </td>
 399 <td>
 400                   <p>
 401                     Includes <code class="computeroutput"><span class="identifier">native_date_time_types</span></code>
 402                     and <code class="computeroutput"><span class="identifier">boost_date_time_types</span></code>
 403                   </p>
 404                 </td>
 405 </tr>
 406 <tr>
 407 <td>
 408                   <p>
 409                     <code class="computeroutput"><span class="identifier">native_date_types</span></code>
 410                   </p>
 411                 </td>
 412 <td>
 413                   <p>
 414                     All types defined in C/C++ standard that have date portion. Currently
 415                     equivalent to <code class="computeroutput"><span class="identifier">native_date_time_types</span></code>.
 416                   </p>
 417                 </td>
 418 </tr>
 419 <tr>
 420 <td>
 421                   <p>
 422                     <code class="computeroutput"><span class="identifier">boost_date_types</span></code>
 423                   </p>
 424                 </td>
 425 <td>
 426                   <p>
 427                     All types defined in <a href="http://www.boost.org/doc/libs/release/doc/html/date_time.html" target="_top">Boost.DateTime</a>
 428                     that have date portion
 429                   </p>
 430                 </td>
 431 </tr>
 432 <tr>
 433 <td>
 434                   <p>
 435                     <code class="computeroutput"><span class="identifier">date_types</span></code>
 436                   </p>
 437                 </td>
 438 <td>
 439                   <p>
 440                     Includes <code class="computeroutput"><span class="identifier">native_date_types</span></code>
 441                     and <code class="computeroutput"><span class="identifier">boost_date_types</span></code>
 442                   </p>
 443                 </td>
 444 </tr>
 445 <tr>
 446 <td>
 447                   <p>
 448                     <code class="computeroutput"><span class="identifier">native_time_types</span></code>
 449                   </p>
 450                 </td>
 451 <td>
 452                   <p>
 453                     All types defined in C/C++ standard that have time portion. Currently
 454                     equivalent to <code class="computeroutput"><span class="identifier">native_date_time_types</span></code>.
 455                   </p>
 456                 </td>
 457 </tr>
 458 <tr>
 459 <td>
 460                   <p>
 461                     <code class="computeroutput"><span class="identifier">boost_time_types</span></code>
 462                   </p>
 463                 </td>
 464 <td>
 465                   <p>
 466                     All types defined in <a href="http://www.boost.org/doc/libs/release/doc/html/date_time.html" target="_top">Boost.DateTime</a>
 467                     that have time portion. Currently equivalent to <code class="computeroutput"><span class="identifier">boost_date_time_types</span></code>.
 468                   </p>
 469                 </td>
 470 </tr>
 471 <tr>
 472 <td>
 473                   <p>
 474                     <code class="computeroutput"><span class="identifier">time_types</span></code>
 475                   </p>
 476                 </td>
 477 <td>
 478                   <p>
 479                     Includes <code class="computeroutput"><span class="identifier">native_time_types</span></code>
 480                     and <code class="computeroutput"><span class="identifier">boost_time_types</span></code>
 481                   </p>
 482                 </td>
 483 </tr>
 484 <tr>
 485 <td>
 486                   <p>
 487                     <code class="computeroutput"><span class="identifier">native_time_duration_types</span></code>
 488                   </p>
 489                 </td>
 490 <td>
 491                   <p>
 492                     All types defined in C/C++ standard that are used to represent
 493                     time duration. Currently only includes <code class="computeroutput"><span class="keyword">double</span></code>,
 494                     as the result type of the <code class="computeroutput"><span class="identifier">difftime</span></code>
 495                     standard function.
 496                   </p>
 497                 </td>
 498 </tr>
 499 <tr>
 500 <td>
 501                   <p>
 502                     <code class="computeroutput"><span class="identifier">boost_time_duration_types</span></code>
 503                   </p>
 504                 </td>
 505 <td>
 506                   <p>
 507                     All time duration types defined in <a href="http://www.boost.org/doc/libs/release/doc/html/date_time.html" target="_top">Boost.DateTime</a>
 508                   </p>
 509                 </td>
 510 </tr>
 511 <tr>
 512 <td>
 513                   <p>
 514                     <code class="computeroutput"><span class="identifier">time_duration_types</span></code>
 515                   </p>
 516                 </td>
 517 <td>
 518                   <p>
 519                     Includes <code class="computeroutput"><span class="identifier">native_time_duration_types</span></code>
 520                     and <code class="computeroutput"><span class="identifier">boost_time_duration_types</span></code>
 521                   </p>
 522                 </td>
 523 </tr>
 524 <tr>
 525 <td>
 526                   <p>
 527                     <code class="computeroutput"><span class="identifier">boost_time_period_types</span></code>
 528                   </p>
 529                 </td>
 530 <td>
 531                   <p>
 532                     All time period types defined in <a href="http://www.boost.org/doc/libs/release/doc/html/date_time.html" target="_top">Boost.DateTime</a>
 533                   </p>
 534                 </td>
 535 </tr>
 536 <tr>
 537 <td>
 538                   <p>
 539                     <code class="computeroutput"><span class="identifier">time_period_types</span></code>
 540                   </p>
 541                 </td>
 542 <td>
 543                   <p>
 544                     Currently equivalent to <code class="computeroutput"><span class="identifier">boost_time_period_types</span></code>
 545                   </p>
 546                 </td>
 547 </tr>
 548 </tbody>
 549 </table></div>
 550 </div>
 551 <br class="table-break">
 552 </div>
 553 <div class="section">
 554 <div class="titlepage"><div><div><h4 class="title">
 555 <a name="log.detailed.utilities.value_ref"></a><a class="link" href="utilities.html#log.detailed.utilities.value_ref" title="Value reference wrapper">Value reference wrapper</a>
 556 </h4></div></div></div>
 557 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><code class="computeroutput"><a class="link" href="../../utilities.html#header.boost.log.utility.value_ref_hpp" title="Header &lt;boost/log/utility/value_ref.hpp&gt;">boost/log/utility/value_ref.hpp</a></code><span class="special">&gt;</span>
 558 </pre>
 559 <p>
 560           The <code class="computeroutput"><a class="link" href="../../boost/log/value_ref.html" title="Class template value_ref">value_ref</a></code> class
 561           template is an optional reference wrapper which is used by the library
 562           to refer to the stored attribute values. To a certain degree it shares
 563           features of <a href="http://www.boost.org/doc/libs/release/libs/optional/index.html" target="_top">Boost.Optional</a>
 564           and <a href="http://www.boost.org/doc/libs/release/doc/html/variant.html" target="_top">Boost.Variant</a>
 565           components.
 566         </p>
 567 <p>
 568           The template has two type parameters. The first is the referred type. It
 569           can also be specified as a <a href="http://www.boost.org/doc/libs/release/libs/mpl/doc/index.html" target="_top">Boost.MPL</a>
 570           type sequence, in which case the <code class="computeroutput"><a class="link" href="../../boost/log/value_ref.html" title="Class template value_ref">value_ref</a></code>
 571           wrapper may refer to either type in the sequence. In this case, the <code class="computeroutput"><span class="identifier">which</span></code> method will return the index of
 572           the referred type within the sequence. The second template parameter is
 573           an optional tag type which can be used to customize formatting behavior.
 574           This tag is forwarded to the <a class="link" href="utilities.html#log.detailed.utilities.manipulators.to_log" title="Customized logging manipulator"><code class="computeroutput"><span class="identifier">to_log</span></code></a> manipulator when the wrapper
 575           is put to a <code class="computeroutput"><a class="link" href="../../boost/log/basic_formatting_ostream.html" title="Class template basic_formatting_ostream">basic_formatting_ostream</a></code>
 576           stream, which is used by the library for record formatting. For an example
 577           see how attribute value extraction is implemented:
 578         </p>
 579 <p>
 580 </p>
 581 <pre class="programlisting"><span class="keyword">void</span> <span class="identifier">print_value_multiple_types</span><span class="special">(</span><span class="identifier">logging</span><span class="special">::</span><span class="identifier">attribute_value</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">attr</span><span class="special">)</span>
 582 <span class="special">{</span>
 583     <span class="comment">// Define the set of expected types of the stored value</span>
 584     <span class="keyword">typedef</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">mpl</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span> <span class="keyword">int</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="special">&gt;</span> <span class="identifier">types</span><span class="special">;</span>
 585
 586     <span class="comment">// Extract a reference to the stored value</span>
 587     <span class="identifier">logging</span><span class="special">::</span><span class="identifier">value_ref</span><span class="special">&lt;</span> <span class="identifier">types</span> <span class="special">&gt;</span> <span class="identifier">val</span> <span class="special">=</span> <span class="identifier">logging</span><span class="special">::</span><span class="identifier">extract</span><span class="special">&lt;</span> <span class="identifier">types</span> <span class="special">&gt;(</span><span class="identifier">attr</span><span class="special">);</span>
 588
 589     <span class="comment">// Check the result</span>
 590     <span class="keyword">if</span> <span class="special">(</span><span class="identifier">val</span><span class="special">)</span>
 591     <span class="special">{</span>
 592         <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Extraction succeeded"</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
 593         <span class="keyword">switch</span> <span class="special">(</span><span class="identifier">val</span><span class="special">.</span><span class="identifier">which</span><span class="special">())</span>
 594         <span class="special">{</span>
 595         <span class="keyword">case</span> <span class="number">0</span><span class="special">:</span>
 596             <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"int: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">val</span><span class="special">.</span><span class="identifier">get</span><span class="special">&lt;</span> <span class="keyword">int</span> <span class="special">&gt;()</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
 597             <span class="keyword">break</span><span class="special">;</span>
 598
 599         <span class="keyword">case</span> <span class="number">1</span><span class="special">:</span>
 600             <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"string: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">val</span><span class="special">.</span><span class="identifier">get</span><span class="special">&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="special">&gt;()</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
 601             <span class="keyword">break</span><span class="special">;</span>
 602         <span class="special">}</span>
 603     <span class="special">}</span>
 604     <span class="keyword">else</span>
 605         <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Extraction failed"</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
 606 <span class="special">}</span>
 607 </pre>
 608 <p>
 609         </p>
 610 <p>
 611           <a href="../../../../../../libs/log/example/doc/attr_value_extraction.cpp" target="_top">See
 612           the complete code</a>.
 613         </p>
 614 <p>
 615           The <code class="computeroutput"><a class="link" href="../../boost/log/value_ref.html" title="Class template value_ref">value_ref</a></code> wrapper
 616           also supports applying a visitor function object to the referred object.
 617           This can be done by calling one of the following methods:
 618         </p>
 619 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 620 <li class="listitem">
 621               <code class="computeroutput"><span class="identifier">apply_visitor</span></code>. This
 622               method should only be used on a valid (non-empty) reference. The method
 623               returns the visitor result.
 624             </li>
 625 <li class="listitem">
 626               <code class="computeroutput"><span class="identifier">apply_visitor_optional</span></code>.
 627               The method checks if the reference is valid and applies the visitor
 628               to the referred value if it is. The method returns the visitor result
 629               wrapped into <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span></code>
 630               which will be filled only if the reference is valid.
 631             </li>
 632 <li class="listitem">
 633               <code class="computeroutput"><span class="identifier">apply_visitor_or_default</span></code>.
 634               If the reference is valid, the method applies the visitor on the referred
 635               value and returns its result. Otherwise the method returns a default
 636               value passed as the second argument.
 637             </li>
 638 </ul></div>
 639 <div class="note"><table border="0" summary="Note">
 640 <tr>
 641 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../doc/src/images/note.png"></td>
 642 <th align="left">Note</th>
 643 </tr>
 644 <tr><td align="left" valign="top"><p>
 645             Regardless of the method used, the visitor function object <span class="underline">must</span> define the <code class="computeroutput"><span class="identifier">result_type</span></code>
 646             typedef. Polymorphic visitors are not supported as this would complicate
 647             the <code class="computeroutput"><a class="link" href="../../boost/log/value_ref.html" title="Class template value_ref">value_ref</a></code> interface
 648             too much. This requirement also precludes free functions and C++11 lambda
 649             functions from being used as visitors. Please, use <a href="http://www.boost.org/doc/libs/release/libs/bind/bind.html" target="_top">Boost.Bind</a>
 650             or similar wrappers in such cases.
 651           </p></td></tr>
 652 </table></div>
 653 <p>
 654           Here is an example of applying a visitor:
 655         </p>
 656 <p>
 657 </p>
 658 <pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">hash_visitor</span>
 659 <span class="special">{</span>
 660     <span class="keyword">typedef</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">result_type</span><span class="special">;</span>
 661
 662     <span class="identifier">result_type</span> <span class="keyword">operator</span><span class="special">()</span> <span class="special">(</span><span class="keyword">int</span> <span class="identifier">val</span><span class="special">)</span> <span class="keyword">const</span>
 663     <span class="special">{</span>
 664         <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">h</span> <span class="special">=</span> <span class="identifier">val</span><span class="special">;</span>
 665         <span class="identifier">h</span> <span class="special">=</span> <span class="special">(</span><span class="identifier">h</span> <span class="special">&lt;&lt;</span> <span class="number">15</span><span class="special">)</span> <span class="special">+</span> <span class="identifier">h</span><span class="special">;</span>
 666         <span class="identifier">h</span> <span class="special">^=</span> <span class="special">(</span><span class="identifier">h</span> <span class="special">&gt;&gt;</span> <span class="number">6</span><span class="special">)</span> <span class="special">+</span> <span class="special">(</span><span class="identifier">h</span> <span class="special">&lt;&lt;</span> <span class="number">7</span><span class="special">);</span>
 667         <span class="keyword">return</span> <span class="identifier">h</span><span class="special">;</span>
 668     <span class="special">}</span>
 669
 670     <span class="identifier">result_type</span> <span class="keyword">operator</span><span class="special">()</span> <span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">val</span><span class="special">)</span> <span class="keyword">const</span>
 671     <span class="special">{</span>
 672         <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">h</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span>
 673         <span class="keyword">for</span> <span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">::</span><span class="identifier">const_iterator</span> <span class="identifier">it</span> <span class="special">=</span> <span class="identifier">val</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">end</span> <span class="special">=</span> <span class="identifier">val</span><span class="special">.</span><span class="identifier">end</span><span class="special">();</span> <span class="identifier">it</span> <span class="special">!=</span> <span class="identifier">end</span><span class="special">;</span> <span class="special">++</span><span class="identifier">it</span><span class="special">)</span>
 674             <span class="identifier">h</span> <span class="special">+=</span> <span class="special">*</span><span class="identifier">it</span><span class="special">;</span>
 675
 676         <span class="identifier">h</span> <span class="special">=</span> <span class="special">(</span><span class="identifier">h</span> <span class="special">&lt;&lt;</span> <span class="number">15</span><span class="special">)</span> <span class="special">+</span> <span class="identifier">h</span><span class="special">;</span>
 677         <span class="identifier">h</span> <span class="special">^=</span> <span class="special">(</span><span class="identifier">h</span> <span class="special">&gt;&gt;</span> <span class="number">6</span><span class="special">)</span> <span class="special">+</span> <span class="special">(</span><span class="identifier">h</span> <span class="special">&lt;&lt;</span> <span class="number">7</span><span class="special">);</span>
 678         <span class="keyword">return</span> <span class="identifier">h</span><span class="special">;</span>
 679     <span class="special">}</span>
 680 <span class="special">};</span>
 681
 682 <span class="keyword">void</span> <span class="identifier">hash_value</span><span class="special">(</span><span class="identifier">logging</span><span class="special">::</span><span class="identifier">attribute_value</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">attr</span><span class="special">)</span>
 683 <span class="special">{</span>
 684     <span class="comment">// Define the set of expected types of the stored value</span>
 685     <span class="keyword">typedef</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">mpl</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span> <span class="keyword">int</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="special">&gt;</span> <span class="identifier">types</span><span class="special">;</span>
 686
 687     <span class="comment">// Extract the stored value</span>
 688     <span class="identifier">logging</span><span class="special">::</span><span class="identifier">value_ref</span><span class="special">&lt;</span> <span class="identifier">types</span> <span class="special">&gt;</span> <span class="identifier">val</span> <span class="special">=</span> <span class="identifier">logging</span><span class="special">::</span><span class="identifier">extract</span><span class="special">&lt;</span> <span class="identifier">types</span> <span class="special">&gt;(</span><span class="identifier">attr</span><span class="special">);</span>
 689
 690     <span class="comment">// Check the result</span>
 691     <span class="keyword">if</span> <span class="special">(</span><span class="identifier">val</span><span class="special">)</span>
 692         <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Extraction succeeded, hash value: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">val</span><span class="special">.</span><span class="identifier">apply_visitor</span><span class="special">(</span><span class="identifier">hash_visitor</span><span class="special">())</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
 693     <span class="keyword">else</span>
 694         <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Extraction failed"</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
 695 <span class="special">}</span>
 696 </pre>
 697 <p>
 698         </p>
 699 </div>
 700 <div class="section">
 701 <div class="titlepage"><div><div><h4 class="title">
 702 <a name="log.detailed.utilities.record_ordering"></a><a class="link" href="utilities.html#log.detailed.utilities.record_ordering" title="Log record ordering">Log record
 703         ordering</a>
 704 </h4></div></div></div>
 705 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><code class="computeroutput"><a class="link" href="../../utilities.html#header.boost.log.utility.record_ordering_hpp" title="Header &lt;boost/log/utility/record_ordering.hpp&gt;">boost/log/utility/record_ordering.hpp</a></code><span class="special">&gt;</span>
 706 </pre>
 707 <p>
 708           There are cases when log records need to be ordered. One possible use case
 709           is storing records in a container or a priority queue. The library provides
 710           two types of record ordering predicates out of the box:
 711         </p>
 712 <h6>
 713 <a name="log.detailed.utilities.record_ordering.h0"></a>
 714           <span class="phrase"><a name="log.detailed.utilities.record_ordering.abstract_record_ordering"></a></span><a class="link" href="utilities.html#log.detailed.utilities.record_ordering.abstract_record_ordering">Abstract
 715           record ordering</a>
 716         </h6>
 717 <p>
 718           The <code class="computeroutput"><a class="link" href="../../boost/log/abstract_ordering.html" title="Class template abstract_ordering">abstract_ordering</a></code>
 719           class allows application of a quick opaque ordering. The result of this
 720           ordering is not stable between different runs of the application and in
 721           general cannot be predicted before the predicate is applied, however it
 722           provides the best performance. The <code class="computeroutput"><a class="link" href="../../boost/log/abstract_ordering.html" title="Class template abstract_ordering">abstract_ordering</a></code>
 723           class is a template that is specialized with an optional predicate function
 724           that will be able to compare <code class="computeroutput"><span class="keyword">const</span>
 725           <span class="keyword">void</span><span class="special">*</span></code>
 726           pointers. By default an <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">less</span></code>
 727           equivalent is used.
 728         </p>
 729 <pre class="programlisting"><span class="comment">// A set of unique records</span>
 730 <span class="identifier">std</span><span class="special">::</span><span class="identifier">set</span><span class="special">&lt;</span> <span class="identifier">logging</span><span class="special">::</span><span class="identifier">record_view</span><span class="special">,</span> <span class="identifier">logging</span><span class="special">::</span><span class="identifier">abstract_ordering</span><span class="special">&lt;</span> <span class="special">&gt;</span> <span class="special">&gt;</span> <span class="identifier">m_Records</span><span class="special">;</span>
 731 </pre>
 732 <p>
 733           This kind of ordering can be useful if the particular order of log records
 734           is not important but nevertheless some order is required.
 735         </p>
 736 <h6>
 737 <a name="log.detailed.utilities.record_ordering.h1"></a>
 738           <span class="phrase"><a name="log.detailed.utilities.record_ordering.attribute_value_based_ordering"></a></span><a class="link" href="utilities.html#log.detailed.utilities.record_ordering.attribute_value_based_ordering">Attribute
 739           value based ordering</a>
 740         </h6>
 741 <p>
 742           This kind of ordering is implemented with the <code class="computeroutput"><a class="link" href="../../boost/log/attribute_value_ordering.html" title="Class template attribute_value_ordering">attribute_value_ordering</a></code>
 743           class and is based on the attribute values attached to the record. The
 744           predicate will seek for an attribute value with the specified name in both
 745           records being ordered and attempt to compare the attribute values.
 746         </p>
 747 <pre class="programlisting"><span class="comment">// Ordering type definition</span>
 748 <span class="keyword">typedef</span> <span class="identifier">logging</span><span class="special">::</span><span class="identifier">attribute_value_ordering</span><span class="special">&lt;</span>
 749     <span class="keyword">int</span>     <span class="comment">// attribute value type</span>
 750 <span class="special">&gt;</span> <span class="identifier">ordering</span><span class="special">;</span>
 751
 752 <span class="comment">// Records organized into a queue based on the "Severity" attribute value</span>
 753 <span class="identifier">std</span><span class="special">::</span><span class="identifier">priority_queue</span><span class="special">&lt;</span>
 754     <span class="identifier">logging</span><span class="special">::</span><span class="identifier">record_view</span><span class="special">,</span>
 755     <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span> <span class="identifier">logging</span><span class="special">::</span><span class="identifier">record_view</span> <span class="special">&gt;,</span>
 756     <span class="identifier">ordering</span>
 757 <span class="special">&gt;</span> <span class="identifier">m_Records</span><span class="special">(</span><span class="identifier">ordering</span><span class="special">(</span><span class="string">"Severity"</span><span class="special">));</span>
 758 </pre>
 759 <p>
 760           Like the <code class="computeroutput"><a class="link" href="../../boost/log/abstract_ordering.html" title="Class template abstract_ordering">abstract_ordering</a></code>,
 761           <code class="computeroutput"><a class="link" href="../../boost/log/attribute_value_ordering.html" title="Class template attribute_value_ordering">attribute_value_ordering</a></code>
 762           also accepts the second optional template parameter, which should be the
 763           predicate to compare attribute values (<code class="computeroutput"><span class="keyword">int</span></code>s
 764           in the example above). By default, an <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">less</span></code>
 765           equivalent is used.
 766         </p>
 767 <p>
 768           You can also use the <code class="computeroutput"><a class="link" href="../../boost/log/make_att_idm45711343139040.html" title="Function template make_attr_ordering">make_attr_ordering</a></code> generator
 769           function to automatically generate the <code class="computeroutput"><a class="link" href="../../boost/log/attribute_value_ordering.html" title="Class template attribute_value_ordering">attribute_value_ordering</a></code>
 770           instance based on the attribute value name and the ordering function. This
 771           might be useful if the ordering function has a non-trivial type, like the
 772           ones <a href="http://www.boost.org/doc/libs/release/libs/bind/bind.html" target="_top">Boost.Bind</a>
 773           provides.
 774         </p>
 775 </div>
 776 <div class="section">
 777 <div class="titlepage"><div><div><h4 class="title">
 778 <a name="log.detailed.utilities.exception_handlers"></a><a class="link" href="utilities.html#log.detailed.utilities.exception_handlers" title="Exception handlers">Exception
 779         handlers</a>
 780 </h4></div></div></div>
 781 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><code class="computeroutput"><a class="link" href="../../utilities.html#header.boost.log.utility.exception_handler_hpp" title="Header &lt;boost/log/utility/exception_handler.hpp&gt;">boost/log/utility/exception_handler.hpp</a></code><span class="special">&gt;</span>
 782 </pre>
 783 <p>
 784           The library provides exception handling hooks in different places. Tools,
 785           defined in this header, provide an easy way of implementing function objects
 786           suitable for such hooks.
 787         </p>
 788 <p>
 789           An exception handler is a function object that accepts no arguments. The
 790           result of the exception handler is ignored and thus should generally be
 791           <code class="computeroutput"><span class="keyword">void</span></code>. Exception handlers are
 792           called from within <code class="computeroutput"><span class="keyword">catch</span></code> sections
 793           by the library, therefore in order to reacquire the exception object it
 794           has to rethrow it. The header defines an <code class="computeroutput"><a class="link" href="../../boost/log/exception_handler.html" title="Class template exception_handler">exception_handler</a></code>
 795           template functor that does just that and then forwards the exception object
 796           to a unary user-defined functional object. The <code class="computeroutput"><a class="link" href="../../boost/log/make_exc_idm45711349902752.html" title="Function template make_exception_handler">make_exception_handler</a></code>
 797           function can be used to simplify the handler construction. All expected
 798           exception types should be specified explicitly in the call, in the order
 799           they would appear in the <code class="computeroutput"><span class="keyword">catch</span></code>
 800           sections (i.e. from most specific ones to the most general ones).
 801         </p>
 802 <p>
 803 </p>
 804 <pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">my_handler</span>
 805 <span class="special">{</span>
 806     <span class="keyword">typedef</span> <span class="keyword">void</span> <span class="identifier">result_type</span><span class="special">;</span>
 807
 808     <span class="keyword">void</span> <span class="keyword">operator</span><span class="special">()</span> <span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">runtime_error</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">e</span><span class="special">)</span> <span class="keyword">const</span>
 809     <span class="special">{</span>
 810         <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"std::runtime_error: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">e</span><span class="special">.</span><span class="identifier">what</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
 811     <span class="special">}</span>
 812     <span class="keyword">void</span> <span class="keyword">operator</span><span class="special">()</span> <span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">logic_error</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">e</span><span class="special">)</span> <span class="keyword">const</span>
 813     <span class="special">{</span>
 814         <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"std::logic_error: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">e</span><span class="special">.</span><span class="identifier">what</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
 815         <span class="keyword">throw</span><span class="special">;</span>
 816     <span class="special">}</span>
 817 <span class="special">};</span>
 818
 819 <span class="keyword">void</span> <span class="identifier">init_exception_handler</span><span class="special">()</span>
 820 <span class="special">{</span>
 821     <span class="comment">// Setup a global exception handler that will call my_handler::operator()</span>
 822     <span class="comment">// for the specified exception types</span>
 823     <span class="identifier">logging</span><span class="special">::</span><span class="identifier">core</span><span class="special">::</span><span class="identifier">get</span><span class="special">()-&gt;</span><span class="identifier">set_exception_handler</span><span class="special">(</span><span class="identifier">logging</span><span class="special">::</span><span class="identifier">make_exception_handler</span><span class="special">&lt;</span>
 824         <span class="identifier">std</span><span class="special">::</span><span class="identifier">runtime_error</span><span class="special">,</span>
 825         <span class="identifier">std</span><span class="special">::</span><span class="identifier">logic_error</span>
 826     <span class="special">&gt;(</span><span class="identifier">my_handler</span><span class="special">()));</span>
 827 <span class="special">}</span>
 828 </pre>
 829 <p>
 830         </p>
 831 <p>
 832           As you can see, you can either suppress the exception by returning normally
 833           from <code class="computeroutput"><span class="keyword">operator</span><span class="special">()</span></code>
 834           in the user-defined handler functor, or rethrow the exception, in which
 835           case it will propagate further. If it appears that the exception handler
 836           is invoked for an exception type that cannot be caught by any of the specified
 837           types, the exception will be propagated without any processing. In order
 838           to catch such situations, there exists the <code class="computeroutput"><a class="link" href="../../boost/log/nothrow_exception_handler.html" title="Class template nothrow_exception_handler">nothrow_exception_handler</a></code>
 839           class. It invokes the user-defined functor with no arguments if it cannot
 840           determine the exception type.
 841         </p>
 842 <p>
 843 </p>
 844 <pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">my_handler_nothrow</span>
 845 <span class="special">{</span>
 846     <span class="keyword">typedef</span> <span class="keyword">void</span> <span class="identifier">result_type</span><span class="special">;</span>
 847
 848     <span class="keyword">void</span> <span class="keyword">operator</span><span class="special">()</span> <span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">runtime_error</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">e</span><span class="special">)</span> <span class="keyword">const</span>
 849     <span class="special">{</span>
 850         <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"std::runtime_error: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">e</span><span class="special">.</span><span class="identifier">what</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
 851     <span class="special">}</span>
 852     <span class="keyword">void</span> <span class="keyword">operator</span><span class="special">()</span> <span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">logic_error</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">e</span><span class="special">)</span> <span class="keyword">const</span>
 853     <span class="special">{</span>
 854         <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"std::logic_error: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">e</span><span class="special">.</span><span class="identifier">what</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
 855         <span class="keyword">throw</span><span class="special">;</span>
 856     <span class="special">}</span>
 857     <span class="keyword">void</span> <span class="keyword">operator</span><span class="special">()</span> <span class="special">()</span> <span class="keyword">const</span>
 858     <span class="special">{</span>
 859         <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"unknown exception"</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
 860     <span class="special">}</span>
 861 <span class="special">};</span>
 862
 863 <span class="keyword">void</span> <span class="identifier">init_exception_handler_nothrow</span><span class="special">()</span>
 864 <span class="special">{</span>
 865     <span class="comment">// Setup a global exception handler that will call my_handler::operator()</span>
 866     <span class="comment">// for the specified exception types. Note the std::nothrow argument that</span>
 867     <span class="comment">// specifies that all other exceptions should also be passed to the functor.</span>
 868     <span class="identifier">logging</span><span class="special">::</span><span class="identifier">core</span><span class="special">::</span><span class="identifier">get</span><span class="special">()-&gt;</span><span class="identifier">set_exception_handler</span><span class="special">(</span><span class="identifier">logging</span><span class="special">::</span><span class="identifier">make_exception_handler</span><span class="special">&lt;</span>
 869         <span class="identifier">std</span><span class="special">::</span><span class="identifier">runtime_error</span><span class="special">,</span>
 870         <span class="identifier">std</span><span class="special">::</span><span class="identifier">logic_error</span>
 871     <span class="special">&gt;(</span><span class="identifier">my_handler_nothrow</span><span class="special">(),</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">nothrow</span><span class="special">));</span>
 872 <span class="special">}</span>
 873 </pre>
 874 <p>
 875         </p>
 876 <p>
 877           It is sometimes convenient to completely suppress all exceptions at a certain
 878           library level. The <code class="computeroutput"><a class="link" href="../../boost/log/make_exception_suppressor.html" title="Function make_exception_suppressor">make_exception_suppressor</a></code>
 879           function creates an exception handler that simply does nothing upon exception
 880           being caught. For example, this way we can disable all exceptions from
 881           the logging library:
 882         </p>
 883 <pre class="programlisting"><span class="keyword">void</span> <span class="identifier">init_logging</span><span class="special">()</span>
 884 <span class="special">{</span>
 885     <span class="identifier">boost</span><span class="special">::</span><span class="identifier">shared_ptr</span><span class="special">&lt;</span> <span class="identifier">logging</span><span class="special">::</span><span class="identifier">core</span> <span class="special">&gt;</span> <span class="identifier">core</span> <span class="special">=</span> <span class="identifier">logging</span><span class="special">::</span><span class="identifier">core</span><span class="special">::</span><span class="identifier">get</span><span class="special">();</span>
 886
 887     <span class="comment">// Disable all exceptions</span>
 888     <span class="identifier">core</span><span class="special">-&gt;</span><span class="identifier">set_exception_handler</span><span class="special">(</span><span class="identifier">logging</span><span class="special">::</span><span class="identifier">make_exception_suppressor</span><span class="special">());</span>
 889 <span class="special">}</span>
 890 </pre>
 891 </div>
 892 <div class="section">
 893 <div class="titlepage"><div><div><h4 class="title">
 894 <a name="log.detailed.utilities.manipulators"></a><a class="link" href="utilities.html#log.detailed.utilities.manipulators" title="Output manipulators">Output manipulators</a>
 895 </h4></div></div></div>
 896 <div class="toc"><dl class="toc">
 897 <dt><span class="section"><a href="utilities.html#log.detailed.utilities.manipulators.to_log">Customized
 898           logging manipulator</a></span></dt>
 899 <dt><span class="section"><a href="utilities.html#log.detailed.utilities.manipulators.add_value">Attribute
 900           value attaching manipulator</a></span></dt>
 901 <dt><span class="section"><a href="utilities.html#log.detailed.utilities.manipulators.dump">Binary
 902           dump manipulator</a></span></dt>
 903 <dt><span class="section"><a href="utilities.html#log.detailed.utilities.manipulators.auto_newline">Automatic
 904           newline insertion</a></span></dt>
 905 </dl></div>
 906 <p>
 907           The library provides a number of stream manipulators that may be useful
 908           in some contexts.
 909         </p>
 910 <div class="section">
 911 <div class="titlepage"><div><div><h5 class="title">
 912 <a name="log.detailed.utilities.manipulators.to_log"></a><a class="link" href="utilities.html#log.detailed.utilities.manipulators.to_log" title="Customized logging manipulator">Customized
 913           logging manipulator</a>
 914 </h5></div></div></div>
 915 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><code class="computeroutput"><a class="link" href="../../utilities.html#header.boost.log.utility.manipulators.to_log_hpp" title="Header &lt;boost/log/utility/manipulators/to_log.hpp&gt;">boost/log/utility/manipulators/to_log.hpp</a></code><span class="special">&gt;</span>
 916 </pre>
 917 <p>
 918             The <code class="computeroutput"><a class="link" href="../../boost/log/to_log_idm45711343255184.html" title="Function template to_log">to_log</a></code>
 919             function creates a stream manipulator that simply outputs the adopted
 920             value to the stream. By default its behavior is equivalent to simply
 921             putting the value to the stream. However, the user is able to overload
 922             the <code class="computeroutput"><span class="keyword">operator</span><span class="special">&lt;&lt;</span></code>
 923             for the adopted value to override formatting behavior when values are
 924             formatted for logging purposes. This is typically desired when the regular
 925             <code class="computeroutput"><span class="keyword">operator</span><span class="special">&lt;&lt;</span></code>
 926             is employed for other tasks (such as serialization) and its behavior
 927             is neither suitable for logging nor can be easily changed. For example:
 928           </p>
 929 <p>
 930 </p>
 931 <pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream</span><span class="special">&amp;</span> <span class="keyword">operator</span><span class="special">&lt;&lt;</span>
 932 <span class="special">(</span>
 933     <span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream</span><span class="special">&amp;</span> <span class="identifier">strm</span><span class="special">,</span>
 934     <span class="identifier">logging</span><span class="special">::</span><span class="identifier">to_log_manip</span><span class="special">&lt;</span> <span class="keyword">int</span> <span class="special">&gt;</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">manip</span>
 935 <span class="special">)</span>
 936 <span class="special">{</span>
 937     <span class="identifier">strm</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">setw</span><span class="special">(</span><span class="number">4</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">setfill</span><span class="special">(</span><span class="char">'0'</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">hex</span> <span class="special">&lt;&lt;</span> <span class="identifier">manip</span><span class="special">.</span><span class="identifier">get</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">dec</span><span class="special">;</span>
 938     <span class="keyword">return</span> <span class="identifier">strm</span><span class="special">;</span>
 939 <span class="special">}</span>
 940
 941 <span class="keyword">void</span> <span class="identifier">test_manip</span><span class="special">()</span>
 942 <span class="special">{</span>
 943     <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Regular output: "</span> <span class="special">&lt;&lt;</span> <span class="number">1010</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
 944     <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Log output: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">logging</span><span class="special">::</span><span class="identifier">to_log</span><span class="special">(</span><span class="number">1010</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
 945 <span class="special">}</span>
 946 </pre>
 947 <p>
 948           </p>
 949 <p>
 950             The second streaming statement in the <code class="computeroutput"><span class="identifier">test_manip</span></code>
 951             function will invoke our custom stream insertion operator which defines
 952             special formatting rules.
 953           </p>
 954 <p>
 955             It is also possible to define different formatting rules for different
 956             value contexts as well. The library uses this feature to allow different
 957             formatting ruled for different attribute values, even if the stored value
 958             type is the same. To do so one has to specify an explicit template argument
 959             for <code class="computeroutput"><a class="link" href="../../boost/log/to_log_idm45711343255184.html" title="Function template to_log">to_log</a></code>,
 960             a tag type, which will be embedded into the manipulator type and thus
 961             will allow to define different insertion operators:
 962           </p>
 963 <p>
 964 </p>
 965 <pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">tag_A</span><span class="special">;</span>
 966 <span class="keyword">struct</span> <span class="identifier">tag_B</span><span class="special">;</span>
 967
 968 <span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream</span><span class="special">&amp;</span> <span class="keyword">operator</span><span class="special">&lt;&lt;</span>
 969 <span class="special">(</span>
 970     <span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream</span><span class="special">&amp;</span> <span class="identifier">strm</span><span class="special">,</span>
 971     <span class="identifier">logging</span><span class="special">::</span><span class="identifier">to_log_manip</span><span class="special">&lt;</span> <span class="keyword">int</span><span class="special">,</span> <span class="identifier">tag_A</span> <span class="special">&gt;</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">manip</span>
 972 <span class="special">)</span>
 973 <span class="special">{</span>
 974     <span class="identifier">strm</span> <span class="special">&lt;&lt;</span> <span class="string">"A["</span> <span class="special">&lt;&lt;</span> <span class="identifier">manip</span><span class="special">.</span><span class="identifier">get</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="string">"]"</span><span class="special">;</span>
 975     <span class="keyword">return</span> <span class="identifier">strm</span><span class="special">;</span>
 976 <span class="special">}</span>
 977
 978 <span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream</span><span class="special">&amp;</span> <span class="keyword">operator</span><span class="special">&lt;&lt;</span>
 979 <span class="special">(</span>
 980     <span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream</span><span class="special">&amp;</span> <span class="identifier">strm</span><span class="special">,</span>
 981     <span class="identifier">logging</span><span class="special">::</span><span class="identifier">to_log_manip</span><span class="special">&lt;</span> <span class="keyword">int</span><span class="special">,</span> <span class="identifier">tag_B</span> <span class="special">&gt;</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">manip</span>
 982 <span class="special">)</span>
 983 <span class="special">{</span>
 984     <span class="identifier">strm</span> <span class="special">&lt;&lt;</span> <span class="string">"B["</span> <span class="special">&lt;&lt;</span> <span class="identifier">manip</span><span class="special">.</span><span class="identifier">get</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="string">"]"</span><span class="special">;</span>
 985     <span class="keyword">return</span> <span class="identifier">strm</span><span class="special">;</span>
 986 <span class="special">}</span>
 987
 988 <span class="keyword">void</span> <span class="identifier">test_manip_with_tag</span><span class="special">()</span>
 989 <span class="special">{</span>
 990     <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Regular output: "</span> <span class="special">&lt;&lt;</span> <span class="number">1010</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
 991     <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Log output A: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">logging</span><span class="special">::</span><span class="identifier">to_log</span><span class="special">&lt;</span> <span class="identifier">tag_A</span> <span class="special">&gt;(</span><span class="number">1010</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
 992     <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Log output B: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">logging</span><span class="special">::</span><span class="identifier">to_log</span><span class="special">&lt;</span> <span class="identifier">tag_B</span> <span class="special">&gt;(</span><span class="number">1010</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
 993 <span class="special">}</span>
 994 </pre>
 995 <p>
 996           </p>
 997 <p>
 998             <a href="../../../../../../libs/log/example/doc/util_manip_to_log.cpp" target="_top">See the
 999             complete code</a>.
1000           </p>
1001 <div class="note"><table border="0" summary="Note">
1002 <tr>
1003 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../doc/src/images/note.png"></td>
1004 <th align="left">Note</th>
1005 </tr>
1006 <tr><td align="left" valign="top"><p>
1007               The library uses <code class="computeroutput"><a class="link" href="../../boost/log/basic_formatting_ostream.html" title="Class template basic_formatting_ostream">basic_formatting_ostream</a></code>
1008               stream type for record formatting, so when customizing attribute value
1009               formatting rules the <code class="computeroutput"><span class="keyword">operator</span><span class="special">&lt;&lt;</span></code> must use <code class="computeroutput"><a class="link" href="../../boost/log/basic_formatting_ostream.html" title="Class template basic_formatting_ostream">basic_formatting_ostream</a></code>
1010               instead of <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream</span></code>.
1011             </p></td></tr>
1012 </table></div>
1013 </div>
1014 <div class="section">
1015 <div class="titlepage"><div><div><h5 class="title">
1016 <a name="log.detailed.utilities.manipulators.add_value"></a><a class="link" href="utilities.html#log.detailed.utilities.manipulators.add_value" title="Attribute value attaching manipulator">Attribute
1017           value attaching manipulator</a>
1018 </h5></div></div></div>
1019 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><code class="computeroutput"><a class="link" href="../../utilities.html#header.boost.log.utility.manipulators.add_value_hpp" title="Header &lt;boost/log/utility/manipulators/add_value.hpp&gt;">boost/log/utility/manipulators/add_value.hpp</a></code><span class="special">&gt;</span>
1020 </pre>
1021 <p>
1022             The <code class="computeroutput"><a class="link" href="../../boost/log/add_value.html" title="Function add_value">add_value</a></code>
1023             function creates a manipulator that attaches an attribute value to a
1024             log record. This manipulator can only be used in streaming expressions
1025             with the <code class="computeroutput"><a class="link" href="../../boost/log/basic_record_ostream.html" title="Class template basic_record_ostream">basic_record_ostream</a></code>
1026             stream type (which is the case when log record message is formatted).
1027             Since the message text is only formatted after filtering, attribute values
1028             attached with this manipulator do not affect filtering and can only be
1029             used in formatters and sinks themselves.
1030           </p>
1031 <p>
1032             In addition to the value itself, the manipulator also requires the attribute
1033             name to be provided. For example:
1034           </p>
1035 <pre class="programlisting"><span class="comment">// Creates a log record with attribute value "MyAttr" of type int attached</span>
1036 <span class="identifier">BOOST_LOG</span><span class="special">(</span><span class="identifier">lg</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">logging</span><span class="special">::</span><span class="identifier">add_value</span><span class="special">(</span><span class="string">"MyAttr"</span><span class="special">,</span> <span class="number">10</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="string">"Hello world!"</span><span class="special">;</span>
1037 </pre>
1038 </div>
1039 <div class="section">
1040 <div class="titlepage"><div><div><h5 class="title">
1041 <a name="log.detailed.utilities.manipulators.dump"></a><a class="link" href="utilities.html#log.detailed.utilities.manipulators.dump" title="Binary dump manipulator">Binary
1042           dump manipulator</a>
1043 </h5></div></div></div>
1044 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><code class="computeroutput"><a class="link" href="../../utilities.html#header.boost.log.utility.manipulators.dump_hpp" title="Header &lt;boost/log/utility/manipulators/dump.hpp&gt;">boost/log/utility/manipulators/dump.hpp</a></code><span class="special">&gt;</span>
1045 </pre>
1046 <p>
1047             The <code class="computeroutput"><a class="link" href="../../boost/log/dump_idm45711343298304.html" title="Function template dump">dump</a></code>
1048             function creates a manipulator that outputs binary contents of a contiguous
1049             memory region. This can be useful for logging some low level binary data,
1050             such as encoded network packets or entries of a binary file. The use
1051             is quite straightforward:
1052           </p>
1053 <pre class="programlisting"><span class="keyword">void</span> <span class="identifier">on_receive</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span> <span class="keyword">unsigned</span> <span class="keyword">char</span> <span class="special">&gt;</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">packet</span><span class="special">)</span>
1054 <span class="special">{</span>
1055     <span class="comment">// Outputs something like "Packet received: 00 01 02 0a 0b 0c"</span>
1056     <span class="identifier">BOOST_LOG</span><span class="special">(</span><span class="identifier">lg</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="string">"Packet received: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">logging</span><span class="special">::</span><span class="identifier">dump</span><span class="special">(</span><span class="identifier">packet</span><span class="special">.</span><span class="identifier">data</span><span class="special">(),</span> <span class="identifier">packet</span><span class="special">.</span><span class="identifier">size</span><span class="special">());</span>
1057 <span class="special">}</span>
1058 </pre>
1059 <p>
1060             The manipulator also allows to limit the amount of data to be output,
1061             in case if the input data can be too large. Just specify the maximum
1062             number of bytes of input to dump as the last argument:
1063           </p>
1064 <pre class="programlisting"><span class="keyword">void</span> <span class="identifier">on_receive</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span> <span class="keyword">unsigned</span> <span class="keyword">char</span> <span class="special">&gt;</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">packet</span><span class="special">)</span>
1065 <span class="special">{</span>
1066     <span class="comment">// Outputs something like "Packet received: 00 01 02 03 04 05 06 07 and 67 bytes more"</span>
1067     <span class="identifier">BOOST_LOG</span><span class="special">(</span><span class="identifier">lg</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="string">"Packet received: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">logging</span><span class="special">::</span><span class="identifier">dump</span><span class="special">(</span><span class="identifier">packet</span><span class="special">.</span><span class="identifier">data</span><span class="special">(),</span> <span class="identifier">packet</span><span class="special">.</span><span class="identifier">size</span><span class="special">(),</span> <span class="number">8</span><span class="special">);</span>
1068 <span class="special">}</span>
1069 </pre>
1070 <p>
1071             There is another manipulator called <code class="computeroutput"><a class="link" href="../../boost/log/dump_ele_idm45711343292832.html" title="Function template dump_elements">dump_elements</a></code> for printing
1072             binary representation of non-byte array elements. The special manipulator
1073             for this case is necessary because the units of the size argument of
1074             <code class="computeroutput"><a class="link" href="../../boost/log/dump_idm45711343298304.html" title="Function template dump">dump</a></code>
1075             can be confusing (is it in bytes or in elements?). Therefore <code class="computeroutput"><a class="link" href="../../boost/log/dump_idm45711343298304.html" title="Function template dump">dump</a></code>
1076             will not compile when used for non-byte input data. <code class="computeroutput"><a class="link" href="../../boost/log/dump_ele_idm45711343292832.html" title="Function template dump_elements">dump_elements</a></code> accepts
1077             the same arguments, and its size-related arguments always designate the
1078             number of elements to process.
1079           </p>
1080 <pre class="programlisting"><span class="keyword">void</span> <span class="identifier">process</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span> <span class="keyword">double</span> <span class="special">&gt;</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">matrix</span><span class="special">)</span>
1081 <span class="special">{</span>
1082     <span class="comment">// Note that dump_elements accepts the number of elements in the matrix, not its size in bytes</span>
1083     <span class="identifier">BOOST_LOG</span><span class="special">(</span><span class="identifier">lg</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="string">"Matrix dump: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">logging</span><span class="special">::</span><span class="identifier">dump_elements</span><span class="special">(</span><span class="identifier">matrix</span><span class="special">.</span><span class="identifier">data</span><span class="special">(),</span> <span class="identifier">matrix</span><span class="special">.</span><span class="identifier">size</span><span class="special">());</span>
1084 <span class="special">}</span>
1085 </pre>
1086 <div class="tip"><table border="0" summary="Tip">
1087 <tr>
1088 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../../../doc/src/images/tip.png"></td>
1089 <th align="left">Tip</th>
1090 </tr>
1091 <tr><td align="left" valign="top"><p>
1092               Both these manipulators can also be used with regular output streams,
1093               not necessarily loggers.
1094             </p></td></tr>
1095 </table></div>
1096 </div>
1097 <div class="section">
1098 <div class="titlepage"><div><div><h5 class="title">
1099 <a name="log.detailed.utilities.manipulators.auto_newline"></a><a class="link" href="utilities.html#log.detailed.utilities.manipulators.auto_newline" title="Automatic newline insertion">Automatic
1100           newline insertion</a>
1101 </h5></div></div></div>
1102 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><code class="computeroutput"><a class="link" href="../../utilities.html#header.boost.log.utility.manipulators.auto_newline_hpp" title="Header &lt;boost/log/utility/manipulators/auto_newline.hpp&gt;">boost/log/utility/manipulators/auto_newline.hpp</a></code><span class="special">&gt;</span>
1103 </pre>
1104 <p>
1105             Sometimes it can be useful to be able to insert a newline character in
1106             the output stream, but only if it hasn't been inserted as part of the
1107             previous output. For example, if a string may or may not end with a newline,
1108             and we cannot easily tell which one it is each time. The <code class="computeroutput"><span class="identifier">auto_newline</span></code> manipulator can be used
1109             to ensure that all such strings are reliably terminated with a newline
1110             and there are no duplicate newline characters. The manipulator will insert
1111             a newline unless the last character inserted into the stream before it
1112             was a newline. Its use is similar to standard stream manipulators:
1113           </p>
1114 <pre class="programlisting"><span class="identifier">BOOST_LOG</span><span class="special">(</span><span class="identifier">lg</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="string">"Parameter: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">param</span><span class="special">.</span><span class="identifier">name</span> <span class="special">&lt;&lt;</span> <span class="string">", value: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">param</span><span class="special">.</span><span class="identifier">value</span> <span class="special">&lt;&lt;</span> <span class="identifier">logging</span><span class="special">::</span><span class="identifier">auto_newline</span><span class="special">;</span>
1115 </pre>
1116 <div class="note"><table border="0" summary="Note">
1117 <tr>
1118 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../doc/src/images/note.png"></td>
1119 <th align="left">Note</th>
1120 </tr>
1121 <tr><td align="left" valign="top"><p>
1122               This manipulator inspects previous output to the stream, and therefore
1123               can only be used with Boost.Log streams based on <code class="computeroutput"><a class="link" href="../../boost/log/basic_formatting_ostream.html" title="Class template basic_formatting_ostream">basic_formatting_ostream</a></code>.
1124             </p></td></tr>
1125 </table></div>
1126 </div>
1127 </div>
1128 <div class="section">
1129 <div class="titlepage"><div><div><h4 class="title">
1130 <a name="log.detailed.utilities.ipc"></a><a class="link" href="utilities.html#log.detailed.utilities.ipc" title="Interprocess communication tools">Interprocess communication
1131         tools</a>
1132 </h4></div></div></div>
1133 <div class="toc"><dl class="toc">
1134 <dt><span class="section"><a href="utilities.html#log.detailed.utilities.ipc.object_name">Resource
1135           name wrapper</a></span></dt>
1136 <dt><span class="section"><a href="utilities.html#log.detailed.utilities.ipc.reliable_message_queue">Reliable
1137           message queue</a></span></dt>
1138 </dl></div>
1139 <div class="section">
1140 <div class="titlepage"><div><div><h5 class="title">
1141 <a name="log.detailed.utilities.ipc.object_name"></a><a class="link" href="utilities.html#log.detailed.utilities.ipc.object_name" title="Resource name wrapper">Resource
1142           name wrapper</a>
1143 </h5></div></div></div>
1144 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><code class="computeroutput"><a class="link" href="../../utilities.html#header.boost.log.utility.ipc.object_name_hpp" title="Header &lt;boost/log/utility/ipc/object_name.hpp&gt;">boost/log/utility/ipc/object_name.hpp</a></code><span class="special">&gt;</span>
1145 </pre>
1146 <p>
1147             In modern operating systems process-shared system resources are typically
1148             identified with names. Unfortunately, different systems have different
1149             requirements on the name syntax and allowed character set. Additionally,
1150             some systems offer support for namespaces in order to avoid name clashes.
1151             The <code class="computeroutput"><a class="link" href="../../boost/log/ipc/object_name.html" title="Class object_name">object_name</a></code>
1152             class is intended to hide these differences.
1153           </p>
1154 <p>
1155             An object name can be constructed from a UTF-8 string identifier and
1156             a scope. A portable identifier can contain the following characters:
1157           </p>
1158 <pre class="programlisting">A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
1159 a b c d e f g h i j k l m n o p q r s t u v w x y z
1160 0 1 2 3 4 5 6 7 8 9 . _ -
1161 </pre>
1162 <div class="note"><table border="0" summary="Note">
1163 <tr>
1164 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../doc/src/images/note.png"></td>
1165 <th align="left">Note</th>
1166 </tr>
1167 <tr><td align="left" valign="top"><p>
1168               The character set corresponds to <a href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_278" target="_top">POSIX
1169               Portable Filename Character Set</a>.
1170             </p></td></tr>
1171 </table></div>
1172 <p>
1173             Use of other characters may result in non-portable system-specific behavior.
1174           </p>
1175 <p>
1176             The scope is identified with the <code class="computeroutput"><span class="identifier">object_name</span><span class="special">::</span><span class="identifier">scope</span></code>
1177             enumeration:
1178           </p>
1179 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1180 <li class="listitem">
1181                 <code class="computeroutput"><span class="identifier">global</span></code> - The name
1182                 has global scope; any process in the system has the potential to
1183                 open the resource identified by the name. On some systems this scope
1184                 may not be available or require elevated privileges.
1185               </li>
1186 <li class="listitem">
1187                 <code class="computeroutput"><span class="identifier">user</span></code> - The name is
1188                 limited to processes running under the current user.
1189               </li>
1190 <li class="listitem">
1191                 <code class="computeroutput"><span class="identifier">session</span></code> - The name
1192                 is limited to processes running in the current login session.
1193               </li>
1194 <li class="listitem">
1195                 <code class="computeroutput"><span class="identifier">process_group</span></code> - The
1196                 name is limited to processes running in the current process group.
1197                 Currently, on Windows all processes running in the current session
1198                 are considered members of the same process group. This may change
1199                 in future.
1200               </li>
1201 </ul></div>
1202 <p>
1203             The scopes are not overlapping. For instance, if an object is created
1204             in the global scope, the object cannot be opened with the same name but
1205             in user's scope. Some of the scopes may require elevated privileges to
1206             create or open objects in.
1207           </p>
1208 <div class="warning"><table border="0" summary="Warning">
1209 <tr>
1210 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../../../doc/src/images/warning.png"></td>
1211 <th align="left">Warning</th>
1212 </tr>
1213 <tr><td align="left" valign="top"><p>
1214               Object name scoping should not be considered a security measure. Objects
1215               may still be accessible by processes outside of their name scopes.
1216               The main purpose of the scopes is to avoid name clashes between different
1217               processes using <code class="computeroutput"><a class="link" href="../../boost/log/ipc/object_name.html" title="Class object_name">object_name</a></code>.
1218               Use access permissions for security control.
1219             </p></td></tr>
1220 </table></div>
1221 </div>
1222 <div class="section">
1223 <div class="titlepage"><div><div><h5 class="title">
1224 <a name="log.detailed.utilities.ipc.reliable_message_queue"></a><a class="link" href="utilities.html#log.detailed.utilities.ipc.reliable_message_queue" title="Reliable message queue">Reliable
1225           message queue</a>
1226 </h5></div></div></div>
1227 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><code class="computeroutput"><a class="link" href="../../utilities.html#header.boost.log.utility.ipc.reliable_message_queue_hpp" title="Header &lt;boost/log/utility/ipc/reliable_message_queue.hpp&gt;">boost/log/utility/ipc/reliable_message_queue.hpp</a></code><span class="special">&gt;</span>
1228 </pre>
1229 <p>
1230             The <code class="computeroutput"><a class="link" href="../../boost/log/ipc/reliable_message_queue.html" title="Class reliable_message_queue">reliable_message_queue</a></code>
1231             class implements a reliable one-way channel of passing messages from
1232             one or multiple writers to a single reader. The format of the messages
1233             is user-defined and must be consistent across all writers and the reader.
1234             The queue does not enforce any specific format of the messages, other
1235             than they should be supplied as a contiguous array of bytes. The queue
1236             internally uses a process-shared storage identified by an <a class="link" href="utilities.html#log.detailed.utilities.ipc.object_name" title="Resource name wrapper">object
1237             name</a> (the queue name).
1238           </p>
1239 <p>
1240             The queue storage is organized as a fixed number of blocks of a fixed
1241             size. The block size must be an integer power of 2 and is expressed in
1242             bytes. Each written message, together with some metadata added by the
1243             queue, consumes an integer number of blocks. Each read message received
1244             by the reader releases the blocks allocated for that message. As such
1245             the maximum size of a message is slightly less than block size times
1246             capacity of the queue. For efficiency, it is recommended to choose block
1247             size large enough to accommodate most of the messages to be passed through
1248             the queue. The queue is considered empty when no messages are enqueued
1249             (all blocks are free). The queue is considered full at the point of enqueueing
1250             a message when there is not enough free blocks to accommodate the message.
1251           </p>
1252 <p>
1253             The queue is reliable in that it will not drop successfully sent messages
1254             that are not received by the reader, other than the case when a non-empty
1255             queue is destroyed by the last user. If a message cannot be enqueued
1256             by the writer because the queue is full, the queue will act depending
1257             on the overflow policy specified at the queue creation:
1258           </p>
1259 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1260 <li class="listitem">
1261                 <code class="computeroutput"><span class="identifier">block_on_overflow</span></code>
1262                 - Block the thread until there is enough space to enqueue the message
1263                 or the operation is aborted by calling <code class="computeroutput"><span class="identifier">stop_local</span></code>.
1264               </li>
1265 <li class="listitem">
1266                 <code class="computeroutput"><span class="identifier">fail_on_overflow</span></code>
1267                 - Return an error code from the send operation. The error code is
1268                 <code class="computeroutput"><span class="identifier">operation_result</span><span class="special">::</span><span class="identifier">no_space</span></code>.
1269               </li>
1270 <li class="listitem">
1271                 <code class="computeroutput"><span class="identifier">throw_on_overflow</span></code>
1272                 - Throw an exception from the send operation. The exception is <code class="computeroutput"><a class="link" href="../../boost/log/capacity_limit_reached.html" title="Class capacity_limit_reached">capacity_limit_reached</a></code>.
1273               </li>
1274 </ul></div>
1275 <p>
1276             The policy is object local, i.e. different writers and the reader can
1277             have different overflow policies. Here is an example of writing to the
1278             message queue:
1279           </p>
1280 <p>
1281 </p>
1282 <pre class="programlisting"><span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
1283 <span class="special">{</span>
1284     <span class="keyword">typedef</span> <span class="identifier">logging</span><span class="special">::</span><span class="identifier">ipc</span><span class="special">::</span><span class="identifier">reliable_message_queue</span> <span class="identifier">queue_t</span><span class="special">;</span>
1285
1286     <span class="comment">// Create a message_queue_type object that is associated with the interprocess</span>
1287     <span class="comment">// message queue named "ipc_message_queue".</span>
1288     <span class="identifier">queue_t</span> <span class="identifier">queue</span>
1289     <span class="special">(</span>
1290         <span class="identifier">keywords</span><span class="special">::</span><span class="identifier">name</span> <span class="special">=</span> <span class="identifier">logging</span><span class="special">::</span><span class="identifier">ipc</span><span class="special">::</span><span class="identifier">object_name</span><span class="special">(</span><span class="identifier">logging</span><span class="special">::</span><span class="identifier">ipc</span><span class="special">::</span><span class="identifier">object_name</span><span class="special">::</span><span class="identifier">user</span><span class="special">,</span> <span class="string">"ipc_message_queue"</span><span class="special">),</span>
1291         <span class="identifier">keywords</span><span class="special">::</span><span class="identifier">open_mode</span> <span class="special">=</span> <span class="identifier">logging</span><span class="special">::</span><span class="identifier">open_mode</span><span class="special">::</span><span class="identifier">open_or_create</span><span class="special">,</span>  <a class="co" name="log.detailed.utilities.ipc.reliable_message_queue.c0" href="utilities.html#log.detailed.utilities.ipc.reliable_message_queue.c1"><img src="../../../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a>
1292         <span class="identifier">keywords</span><span class="special">::</span><span class="identifier">capacity</span> <span class="special">=</span> <span class="number">256</span><span class="special">,</span>                                  <a class="co" name="log.detailed.utilities.ipc.reliable_message_queue.c2" href="utilities.html#log.detailed.utilities.ipc.reliable_message_queue.c3"><img src="../../../../../../doc/src/images/callouts/2.png" alt="2" border="0"></a>
1293         <span class="identifier">keywords</span><span class="special">::</span><span class="identifier">block_size</span> <span class="special">=</span> <span class="number">1024</span><span class="special">,</span>                               <a class="co" name="log.detailed.utilities.ipc.reliable_message_queue.c4" href="utilities.html#log.detailed.utilities.ipc.reliable_message_queue.c5"><img src="../../../../../../doc/src/images/callouts/3.png" alt="3" border="0"></a>
1294         <span class="identifier">keywords</span><span class="special">::</span><span class="identifier">overflow_policy</span> <span class="special">=</span> <span class="identifier">queue_t</span><span class="special">::</span><span class="identifier">fail_on_overflow</span>      <a class="co" name="log.detailed.utilities.ipc.reliable_message_queue.c6" href="utilities.html#log.detailed.utilities.ipc.reliable_message_queue.c7"><img src="../../../../../../doc/src/images/callouts/4.png" alt="4" border="0"></a>
1295     <span class="special">);</span>
1296
1297     <span class="comment">// Send a message through the queue</span>
1298     <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">message</span> <span class="special">=</span> <span class="string">"Hello, Viewer!"</span><span class="special">;</span>
1299     <span class="identifier">queue_t</span><span class="special">::</span><span class="identifier">operation_result</span> <span class="identifier">result</span> <span class="special">=</span> <span class="identifier">queue</span><span class="special">.</span><span class="identifier">send</span><span class="special">(</span><span class="identifier">message</span><span class="special">.</span><span class="identifier">data</span><span class="special">(),</span> <span class="keyword">static_cast</span><span class="special">&lt;</span> <span class="identifier">queue_t</span><span class="special">::</span><span class="identifier">size_type</span> <span class="special">&gt;(</span><span class="identifier">message</span><span class="special">.</span><span class="identifier">size</span><span class="special">()));</span>
1300
1301     <span class="comment">// See if the message was sent</span>
1302     <span class="keyword">switch</span> <span class="special">(</span><span class="identifier">result</span><span class="special">)</span>
1303     <span class="special">{</span>
1304     <span class="keyword">case</span> <span class="identifier">queue_t</span><span class="special">::</span><span class="identifier">operation_result</span><span class="special">::</span><span class="identifier">succeeded</span><span class="special">:</span>
1305         <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Message sent successfully"</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
1306         <span class="keyword">break</span><span class="special">;</span>
1307
1308     <span class="keyword">case</span> <span class="identifier">queue_t</span><span class="special">::</span><span class="identifier">operation_result</span><span class="special">::</span><span class="identifier">no_space</span><span class="special">:</span>
1309         <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Message could not be sent because the queue is full"</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
1310         <span class="keyword">break</span><span class="special">;</span>
1311
1312     <span class="keyword">case</span> <span class="identifier">queue_t</span><span class="special">::</span><span class="identifier">operation_result</span><span class="special">::</span><span class="identifier">aborted</span><span class="special">:</span>
1313         <span class="comment">// This can happen is overflow_policy is block_on_overflow</span>
1314         <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Message sending operation has been interrupted"</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
1315         <span class="keyword">break</span><span class="special">;</span>
1316     <span class="special">}</span>
1317
1318     <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
1319 <span class="special">}</span>
1320 </pre>
1321 <p>
1322           </p>
1323 <div class="calloutlist"><table border="0" summary="Callout list">
1324 <tr>
1325 <td width="5%" valign="top" align="left"><p><a name="log.detailed.utilities.ipc.reliable_message_queue.c1"></a><a href="#log.detailed.utilities.ipc.reliable_message_queue.c0"><img src="../../../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a> </p></td>
1326 <td valign="top" align="left"><p>
1327                 create the queue, if not yet created
1328               </p></td>
1329 </tr>
1330 <tr>
1331 <td width="5%" valign="top" align="left"><p><a name="log.detailed.utilities.ipc.reliable_message_queue.c3"></a><a href="#log.detailed.utilities.ipc.reliable_message_queue.c2"><img src="../../../../../../doc/src/images/callouts/2.png" alt="2" border="0"></a> </p></td>
1332 <td valign="top" align="left"><p>
1333                 if the queue has to be created, allocate 256 blocks...
1334               </p></td>
1335 </tr>
1336 <tr>
1337 <td width="5%" valign="top" align="left"><p><a name="log.detailed.utilities.ipc.reliable_message_queue.c5"></a><a href="#log.detailed.utilities.ipc.reliable_message_queue.c4"><img src="../../../../../../doc/src/images/callouts/3.png" alt="3" border="0"></a> </p></td>
1338 <td valign="top" align="left"><p>
1339                 ... of 1 KiB each for messages
1340               </p></td>
1341 </tr>
1342 <tr>
1343 <td width="5%" valign="top" align="left"><p><a name="log.detailed.utilities.ipc.reliable_message_queue.c7"></a><a href="#log.detailed.utilities.ipc.reliable_message_queue.c6"><img src="../../../../../../doc/src/images/callouts/4.png" alt="4" border="0"></a> </p></td>
1344 <td valign="top" align="left"><p>
1345                 if the queue is full, return error to the writer
1346               </p></td>
1347 </tr>
1348 </table></div>
1349 <p>
1350             <a href="../../../../../../libs/log/example/doc/util_ipc_reliable_mq_writer.cpp" target="_top">See
1351             the complete code</a>.
1352           </p>
1353 <p>
1354             Typically, the queue would be used for sending log records to a different
1355             process. As such, instead of using the queue for writing directly, one
1356             would use a special sink backend for that. See <a class="link" href="sink_backends.html#log.detailed.sink_backends.text_ipc_message_queue" title="Text IPC message queue backend"><code class="computeroutput"><span class="identifier">text_ipc_message_queue_backend</span></code></a>
1357             documentation.
1358           </p>
1359 <p>
1360             Receiving messages from the queue is similar. Here is an example of a
1361             log viewer that receives messages from the queue and displays them on
1362             the console.
1363           </p>
1364 <p>
1365 </p>
1366 <pre class="programlisting"><span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
1367 <span class="special">{</span>
1368     <span class="keyword">try</span>
1369     <span class="special">{</span>
1370         <span class="keyword">typedef</span> <span class="identifier">logging</span><span class="special">::</span><span class="identifier">ipc</span><span class="special">::</span><span class="identifier">reliable_message_queue</span> <span class="identifier">queue_t</span><span class="special">;</span>
1371
1372         <span class="comment">// Create a message_queue_type object that is associated with the interprocess</span>
1373         <span class="comment">// message queue named "ipc_message_queue".</span>
1374         <span class="identifier">queue_t</span> <span class="identifier">queue</span>
1375         <span class="special">(</span>
1376             <span class="identifier">keywords</span><span class="special">::</span><span class="identifier">name</span> <span class="special">=</span> <span class="identifier">logging</span><span class="special">::</span><span class="identifier">ipc</span><span class="special">::</span><span class="identifier">object_name</span><span class="special">(</span><span class="identifier">logging</span><span class="special">::</span><span class="identifier">ipc</span><span class="special">::</span><span class="identifier">object_name</span><span class="special">::</span><span class="identifier">user</span><span class="special">,</span> <span class="string">"ipc_message_queue"</span><span class="special">),</span>
1377             <span class="identifier">keywords</span><span class="special">::</span><span class="identifier">open_mode</span> <span class="special">=</span> <span class="identifier">logging</span><span class="special">::</span><span class="identifier">open_mode</span><span class="special">::</span><span class="identifier">open_or_create</span><span class="special">,</span>
1378             <span class="identifier">keywords</span><span class="special">::</span><span class="identifier">capacity</span> <span class="special">=</span> <span class="number">256</span><span class="special">,</span>
1379             <span class="identifier">keywords</span><span class="special">::</span><span class="identifier">block_size</span> <span class="special">=</span> <span class="number">1024</span><span class="special">,</span>
1380             <span class="identifier">keywords</span><span class="special">::</span><span class="identifier">overflow_policy</span> <span class="special">=</span> <span class="identifier">queue_t</span><span class="special">::</span><span class="identifier">block_on_overflow</span>
1381         <span class="special">);</span>
1382
1383         <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Viewer process running..."</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
1384
1385         <span class="comment">// Keep reading log messages from the associated message queue and print them on the console.</span>
1386         <span class="comment">// queue.receive() will block if the queue is empty.</span>
1387         <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">message</span><span class="special">;</span>
1388         <span class="keyword">while</span> <span class="special">(</span><span class="identifier">queue</span><span class="special">.</span><span class="identifier">receive</span><span class="special">(</span><span class="identifier">message</span><span class="special">)</span> <span class="special">==</span> <span class="identifier">queue_t</span><span class="special">::</span><span class="identifier">succeeded</span><span class="special">)</span>
1389         <span class="special">{</span>
1390             <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">message</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
1391
1392             <span class="comment">// Clear the buffer for the next message</span>
1393             <span class="identifier">message</span><span class="special">.</span><span class="identifier">clear</span><span class="special">();</span>
1394         <span class="special">}</span>
1395     <span class="special">}</span>
1396     <span class="keyword">catch</span> <span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">exception</span><span class="special">&amp;</span> <span class="identifier">e</span><span class="special">)</span>
1397     <span class="special">{</span>
1398         <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Failure: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">e</span><span class="special">.</span><span class="identifier">what</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
1399     <span class="special">}</span>
1400
1401     <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
1402 <span class="special">}</span>
1403 </pre>
1404 <p>
1405           </p>
1406 <p>
1407             <a href="../../../../../../libs/log/example/doc/sinks_ipc_receiver.cpp" target="_top">See the
1408             complete code</a>.
1409           </p>
1410 <div class="note"><table border="0" summary="Note">
1411 <tr>
1412 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../doc/src/images/note.png"></td>
1413 <th align="left">Note</th>
1414 </tr>
1415 <tr><td align="left" valign="top"><p>
1416               The queue does not guarantee any particular order of received messages
1417               from different writer threads. Messages sent by a particular writer
1418               thread will be received in the order of sending.
1419             </p></td></tr>
1420 </table></div>
1421 <p>
1422             A blocked reader or writer can be unblocked by calling <code class="computeroutput"><span class="identifier">stop_local</span></code>. After this method is called,
1423             all threads blocked on this particular object are released and return
1424             <code class="computeroutput"><span class="identifier">operation_result</span><span class="special">::</span><span class="identifier">aborted</span></code>. The other instances of the
1425             queue (in the current or other processes) are unaffected. In order to
1426             restore the normal functioning of the queue instance after the <code class="computeroutput"><span class="identifier">stop_local</span></code> call the user has to invoke
1427             <code class="computeroutput"><span class="identifier">reset_local</span></code>.
1428           </p>
1429 </div>
1430 </div>
1431 <div class="section">
1432 <div class="titlepage"><div><div><h4 class="title">
1433 <a name="log.detailed.utilities.setup"></a><a class="link" href="utilities.html#log.detailed.utilities.setup" title="Simplified library initialization tools">Simplified library initialization
1434         tools</a>
1435 </h4></div></div></div>
1436 <div class="toc"><dl class="toc">
1437 <dt><span class="section"><a href="utilities.html#log.detailed.utilities.setup.convenience">Convenience
1438           functions</a></span></dt>
1439 <dt><span class="section"><a href="utilities.html#log.detailed.utilities.setup.filter_formatter">Filter
1440           and formatter parsers</a></span></dt>
1441 <dt><span class="section"><a href="utilities.html#log.detailed.utilities.setup.settings">Library initialization
1442           from a settings container</a></span></dt>
1443 <dt><span class="section"><a href="utilities.html#log.detailed.utilities.setup.settings_file">Library
1444           initialization from a settings file</a></span></dt>
1445 </dl></div>
1446 <p>
1447           This part of the library is provided in order to simplify logging initialization
1448           and provide basic tools to develop user-specific initialization mechanisms.
1449           It is known that setup capabilities and preferences may vary widely from
1450           application to application, therefore the library does not attempt to provide
1451           a universal solution for this task. The provided tools are mostly intended
1452           to serve as a quick drop-in support for logging setup and a set of instruments
1453           to implement something more elaborate and more fitting users' needs.
1454         </p>
1455 <p>
1456           Some of the features described in this section will require the separate
1457           library binary, with name based on "boost_log_setup" substring.
1458           This binary depends on the main library.
1459         </p>
1460 <div class="section">
1461 <div class="titlepage"><div><div><h5 class="title">
1462 <a name="log.detailed.utilities.setup.convenience"></a><a class="link" href="utilities.html#log.detailed.utilities.setup.convenience" title="Convenience functions">Convenience
1463           functions</a>
1464 </h5></div></div></div>
1465 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><code class="computeroutput"><a class="link" href="../../utilities.html#header.boost.log.utility.setup.console_hpp" title="Header &lt;boost/log/utility/setup/console.hpp&gt;">boost/log/utility/setup/console.hpp</a></code><span class="special">&gt;</span>
1466 <span class="preprocessor">#include</span> <span class="special">&lt;</span><code class="computeroutput"><a class="link" href="../../utilities.html#header.boost.log.utility.setup.file_hpp" title="Header &lt;boost/log/utility/setup/file.hpp&gt;">boost/log/utility/setup/file.hpp</a></code><span class="special">&gt;</span>
1467 <span class="preprocessor">#include</span> <span class="special">&lt;</span><code class="computeroutput"><a class="link" href="../../utilities.html#header.boost.log.utility.setup.common_attributes_hpp" title="Header &lt;boost/log/utility/setup/common_attributes.hpp&gt;">boost/log/utility/setup/common_attributes.hpp</a></code><span class="special">&gt;</span>
1468 </pre>
1469 <p>
1470             The library provides a number of functions that simplify some common
1471             initialization procedures, like sink and commonly used attributes registration.
1472             This is not much functionality. However, it saves a couple of minutes
1473             of learning the library for a newcomer.
1474           </p>
1475 <p>
1476             Logging to the application console is the simplest way to see the logging
1477             library in action. To achieve this, one can initialize the library with
1478             a single function call, like this:
1479           </p>
1480 <pre class="programlisting"><span class="keyword">int</span> <span class="identifier">main</span><span class="special">(</span><span class="keyword">int</span><span class="special">,</span> <span class="keyword">char</span><span class="special">*[])</span>
1481 <span class="special">{</span>
1482     <span class="comment">// Initialize logging to std::clog</span>
1483     <span class="identifier">logging</span><span class="special">::</span><span class="identifier">add_console_log</span><span class="special">();</span>
1484
1485     <span class="comment">// Here we go, we can write logs right away</span>
1486     <span class="identifier">src</span><span class="special">::</span><span class="identifier">logger</span> <span class="identifier">lg</span><span class="special">;</span>
1487     <span class="identifier">BOOST_LOG</span><span class="special">(</span><span class="identifier">lg</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="string">"Hello world!"</span><span class="special">;</span>
1488
1489     <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
1490 <span class="special">}</span>
1491 </pre>
1492 <p>
1493             Pretty easy, isn't it? There is also the <code class="computeroutput"><span class="identifier">wadd_console_log</span></code>
1494             function for wide-character console. If you want to put logs to some
1495             other standard stream, you can pass the stream to the <code class="computeroutput"><a class="link" href="../../boost/log/add_cons_idm45711343115184.html" title="Function template add_console_log">add_console_log</a></code> function
1496             as an argument. E.g. enabling logging to <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span></code>
1497             instead of <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">clog</span></code> would look like this:
1498           </p>
1499 <pre class="programlisting"><span class="identifier">logging</span><span class="special">::</span><span class="identifier">add_console_log</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">);</span>
1500 </pre>
1501 <p>
1502             What's important, is that you can further manage the console sink if
1503             you save the <code class="computeroutput"><span class="identifier">shared_ptr</span></code>
1504             to the sink that this function returns. This allows you to set up things
1505             like filter, formatter and auto-flush flag.
1506           </p>
1507 <pre class="programlisting"><span class="keyword">int</span> <span class="identifier">main</span><span class="special">(</span><span class="keyword">int</span><span class="special">,</span> <span class="keyword">char</span><span class="special">*[])</span>
1508 <span class="special">{</span>
1509     <span class="comment">// Initialize logging to std::clog</span>
1510     <span class="identifier">boost</span><span class="special">::</span><span class="identifier">shared_ptr</span><span class="special">&lt;</span>
1511         <span class="identifier">sinks</span><span class="special">::</span><span class="identifier">synchronous_sink</span><span class="special">&lt;</span> <span class="identifier">sinks</span><span class="special">::</span><span class="identifier">text_ostream_backend</span> <span class="special">&gt;</span>
1512     <span class="special">&gt;</span> <span class="identifier">sink</span> <span class="special">=</span> <span class="identifier">logging</span><span class="special">::</span><span class="identifier">add_console_log</span><span class="special">();</span>
1513
1514     <span class="identifier">sink</span><span class="special">-&gt;</span><span class="identifier">set_filter</span><span class="special">(</span><span class="identifier">expr</span><span class="special">::</span><span class="identifier">attr</span><span class="special">&lt;</span> <span class="keyword">int</span> <span class="special">&gt;(</span><span class="string">"Severity"</span><span class="special">)</span> <span class="special">&gt;=</span> <span class="number">3</span><span class="special">);</span>
1515     <span class="identifier">sink</span><span class="special">-&gt;</span><span class="identifier">locked_backend</span><span class="special">()-&gt;</span><span class="identifier">auto_flush</span><span class="special">(</span><span class="keyword">true</span><span class="special">);</span>
1516
1517     <span class="comment">// Here we go, we can write logs right away</span>
1518     <span class="identifier">src</span><span class="special">::</span><span class="identifier">logger</span> <span class="identifier">lg</span><span class="special">;</span>
1519     <span class="identifier">BOOST_LOG</span><span class="special">(</span><span class="identifier">lg</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="string">"Hello world!"</span><span class="special">;</span>
1520
1521     <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
1522 <span class="special">}</span>
1523 </pre>
1524 <p>
1525             Similarly to console, one can use a single function call to enable logging
1526             to a file. All you have to do is to provide the file name:
1527           </p>
1528 <pre class="programlisting"><span class="keyword">int</span> <span class="identifier">main</span><span class="special">(</span><span class="keyword">int</span><span class="special">,</span> <span class="keyword">char</span><span class="special">*[])</span>
1529 <span class="special">{</span>
1530     <span class="comment">// Initialize logging to the "test.log" file</span>
1531     <span class="identifier">logging</span><span class="special">::</span><span class="identifier">add_file_log</span><span class="special">(</span><span class="string">"test.log"</span><span class="special">);</span>
1532
1533     <span class="comment">// Here we go, we can write logs right away</span>
1534     <span class="identifier">src</span><span class="special">::</span><span class="identifier">logger</span> <span class="identifier">lg</span><span class="special">;</span>
1535     <span class="identifier">BOOST_LOG</span><span class="special">(</span><span class="identifier">lg</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="string">"Hello world!"</span><span class="special">;</span>
1536
1537     <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
1538 <span class="special">}</span>
1539 </pre>
1540 <p>
1541             The <code class="computeroutput"><a class="link" href="../../boost/log/add_cons_idm45711343115184.html" title="Function template add_console_log">add_console_log</a></code>
1542             and <code class="computeroutput"><a class="link" href="../../boost/log/add_file_log.html" title="Function template add_file_log">add_file_log</a></code>
1543             functions do not conflict and may be combined freely, so it is possible
1544             to set up logging to the console and a couple of files, including filtering
1545             and formatting, in about 10 lines of code.
1546           </p>
1547 <p>
1548             Lastly, there is an <code class="computeroutput"><a class="link" href="../../boost/log/add_common_attributes.html" title="Function add_common_attributes">add_common_attributes</a></code>
1549             function that registers two frequently used attributes: "LineID"
1550             and "TimeStamp". The former counts log record being made and
1551             has attribute value <code class="computeroutput"><span class="keyword">unsigned</span> <span class="keyword">int</span></code>. The latter, as its name implies,
1552             provides the current time for each log record, in the form of <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">posix_time</span><span class="special">::</span><span class="identifier">ptime</span></code> (see <a href="http://www.boost.org/doc/libs/release/doc/html/date_time.html" target="_top">Boost.DateTime</a>).
1553             These two attributes are registered globally, so they will remain available
1554             in all threads and loggers. This makes the final version of our code
1555             sample look something like this:
1556           </p>
1557 <pre class="programlisting"><span class="keyword">int</span> <span class="identifier">main</span><span class="special">(</span><span class="keyword">int</span><span class="special">,</span> <span class="keyword">char</span><span class="special">*[])</span>
1558 <span class="special">{</span>
1559     <span class="comment">// Initialize sinks</span>
1560     <span class="identifier">logging</span><span class="special">::</span><span class="identifier">add_console_log</span><span class="special">()-&gt;</span><span class="identifier">set_filter</span><span class="special">(</span><span class="identifier">expr</span><span class="special">::</span><span class="identifier">attr</span><span class="special">&lt;</span> <span class="keyword">int</span> <span class="special">&gt;(</span><span class="string">"Severity"</span><span class="special">)</span> <span class="special">&gt;=</span> <span class="number">4</span><span class="special">);</span>
1561
1562     <span class="identifier">logging</span><span class="special">::</span><span class="identifier">formatter</span> <span class="identifier">formatter</span> <span class="special">=</span>
1563         <span class="identifier">expr</span><span class="special">::</span><span class="identifier">stream</span>
1564             <span class="special">&lt;&lt;</span> <span class="identifier">expr</span><span class="special">::</span><span class="identifier">attr</span><span class="special">&lt;</span> <span class="keyword">unsigned</span> <span class="keyword">int</span> <span class="special">&gt;(</span><span class="string">"LineID"</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="string">": "</span>
1565             <span class="special">&lt;&lt;</span> <span class="identifier">expr</span><span class="special">::</span><span class="identifier">format_date_time</span><span class="special">&lt;</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">posix_time</span><span class="special">::</span><span class="identifier">ptime</span> <span class="special">&gt;(</span><span class="string">"TimeStamp"</span><span class="special">,</span> <span class="string">"%Y-%m-%d %H:%M:%S"</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="string">" *"</span>
1566             <span class="special">&lt;&lt;</span> <span class="identifier">expr</span><span class="special">::</span><span class="identifier">attr</span><span class="special">&lt;</span> <span class="keyword">int</span> <span class="special">&gt;(</span><span class="string">"Severity"</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="string">"* "</span>
1567             <span class="special">&lt;&lt;</span> <span class="identifier">expr</span><span class="special">::</span><span class="identifier">message</span><span class="special">;</span>
1568
1569     <span class="identifier">logging</span><span class="special">::</span><span class="identifier">add_file_log</span><span class="special">(</span><span class="string">"complete.log"</span><span class="special">)-&gt;</span><span class="identifier">set_formatter</span><span class="special">(</span><span class="identifier">formatter</span><span class="special">);</span>
1570
1571     <span class="identifier">boost</span><span class="special">::</span><span class="identifier">shared_ptr</span><span class="special">&lt;</span>
1572         <span class="identifier">sinks</span><span class="special">::</span><span class="identifier">synchronous_sink</span><span class="special">&lt;</span> <span class="identifier">sinks</span><span class="special">::</span><span class="identifier">text_ostream_backend</span> <span class="special">&gt;</span>
1573     <span class="special">&gt;</span> <span class="identifier">sink</span> <span class="special">=</span> <span class="identifier">logging</span><span class="special">::</span><span class="identifier">add_file_log</span><span class="special">(</span><span class="string">"essential.log"</span><span class="special">);</span>
1574     <span class="identifier">sink</span><span class="special">-&gt;</span><span class="identifier">set_formatter</span><span class="special">(</span><span class="identifier">formatter</span><span class="special">);</span>
1575     <span class="identifier">sink</span><span class="special">-&gt;</span><span class="identifier">set_filter</span><span class="special">(</span><span class="identifier">expr</span><span class="special">::</span><span class="identifier">attr</span><span class="special">&lt;</span> <span class="keyword">int</span> <span class="special">&gt;(</span><span class="string">"Severity"</span><span class="special">)</span> <span class="special">&gt;=</span> <span class="number">1</span><span class="special">);</span>
1576
1577     <span class="comment">// Register common attributes</span>
1578     <span class="identifier">logging</span><span class="special">::</span><span class="identifier">add_common_attributes</span><span class="special">();</span>
1579
1580     <span class="comment">// Here we go, we can write logs</span>
1581     <span class="identifier">src</span><span class="special">::</span><span class="identifier">logger</span> <span class="identifier">lg</span><span class="special">;</span>
1582     <span class="identifier">BOOST_LOG</span><span class="special">(</span><span class="identifier">lg</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="string">"Hello world!"</span><span class="special">;</span>
1583
1584     <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
1585 <span class="special">}</span>
1586 </pre>
1587 </div>
1588 <div class="section">
1589 <div class="titlepage"><div><div><h5 class="title">
1590 <a name="log.detailed.utilities.setup.filter_formatter"></a><a class="link" href="utilities.html#log.detailed.utilities.setup.filter_formatter" title="Filter and formatter parsers">Filter
1591           and formatter parsers</a>
1592 </h5></div></div></div>
1593 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><code class="computeroutput"><a class="link" href="../../utilities.html#header.boost.log.utility.setup.filter_parser_hpp" title="Header &lt;boost/log/utility/setup/filter_parser.hpp&gt;">boost/log/utility/setup/filter_parser.hpp</a></code><span class="special">&gt;</span>
1594 <span class="preprocessor">#include</span> <span class="special">&lt;</span><code class="computeroutput"><a class="link" href="../../utilities.html#header.boost.log.utility.setup.formatter_parser_hpp" title="Header &lt;boost/log/utility/setup/formatter_parser.hpp&gt;">boost/log/utility/setup/formatter_parser.hpp</a></code><span class="special">&gt;</span>
1595 </pre>
1596 <p>
1597             Filter and formatter parsers allow constructing filters and formatters
1598             from a descriptive string. The function <code class="computeroutput"><span class="identifier">parse_filter</span></code>
1599             is responsible for recognizing filters and <code class="computeroutput"><span class="identifier">parse_formatter</span></code>
1600             - for recognizing formatters.
1601           </p>
1602 <p>
1603             In the case of filters the string is formed of a sequence of condition
1604             expressions, interconnected with boolean operations. There are two operations
1605             supported: conjunction (designated as "&amp;" or "and")
1606             and disjunction ("|" or "or"). Each condition itself
1607             may be either a single condition or a sub-filter, taken in round brackets.
1608             Each condition can be negated with the "!" sign or "not"
1609             keyword. The condition, if it's not a sub-filter, usually consists of
1610             an attribute name enclosed in percent characters ("%"), a relation
1611             keyword and an operand. The relation and operand may be omitted, in which
1612             case the condition is assumed to be the requirement of the attribute
1613             presence (with any type).
1614           </p>
1615 <pre class="programlisting">filter:
1616     condition { op condition }
1617
1618 op:
1619     &amp;
1620     and
1621     |
1622     or
1623
1624 condition:
1625     !condition
1626     not condition
1627     (filter)
1628     %attribute_name%
1629     %attribute_name% relation operand
1630
1631 relation:
1632     &gt;
1633     &lt;
1634     =
1635     !=
1636     &gt;=
1637     &lt;=
1638     begins_with
1639     ends_with
1640     contains
1641     matches
1642 </pre>
1643 <p>
1644             Below are some examples of filters:
1645           </p>
1646 <div class="table">
1647 <a name="log.detailed.utilities.setup.filter_formatter.examples_of_filters"></a><p class="title"><b>Table&#160;1.8.&#160;Examples of filters</b></p>
1648 <div class="table-contents"><table class="table" summary="Examples of filters">
1649 <colgroup>
1650 <col>
1651 <col>
1652 </colgroup>
1653 <thead><tr>
1654 <th>
1655                     <p>
1656                       Filter string
1657                     </p>
1658                   </th>
1659 <th>
1660                     <p>
1661                       Description
1662                     </p>
1663                   </th>
1664 </tr></thead>
1665 <tbody>
1666 <tr>
1667 <td>
1668                     <p>
1669                       <code class="computeroutput"><span class="special">%</span><span class="identifier">Severity</span><span class="special">%</span></code>
1670                     </p>
1671                   </td>
1672 <td>
1673                     <p>
1674                       The filter returns <code class="computeroutput"><span class="keyword">true</span></code>
1675                       if an attribute value with name "Severity" is found
1676                       in a log record.
1677                     </p>
1678                   </td>
1679 </tr>
1680 <tr>
1681 <td>
1682                     <p>
1683                       <code class="computeroutput"><span class="special">%</span><span class="identifier">Severity</span><span class="special">%</span> <span class="special">&gt;</span>
1684                       <span class="number">3</span></code>
1685                     </p>
1686                   </td>
1687 <td>
1688                     <p>
1689                       The filter returns <code class="computeroutput"><span class="keyword">true</span></code>
1690                       if an attribute value with name "Severity" is found
1691                       and it is greater than 3. The attribute value must be of one
1692                       of the <a class="link" href="utilities.html#log.detailed.utilities.predef_types" title="Predefined type sequences">integral
1693                       types</a>.
1694                     </p>
1695                   </td>
1696 </tr>
1697 <tr>
1698 <td>
1699                     <p>
1700                       !(<code class="computeroutput"><span class="special">%</span><span class="identifier">Ratio</span><span class="special">%</span> <span class="special">&gt;</span>
1701                       <span class="number">0.0</span> <span class="special">&amp;</span>
1702                       <span class="special">%</span><span class="identifier">Ratio</span><span class="special">%</span> <span class="special">&lt;=</span>
1703                       <span class="number">0.5</span><span class="special">)</span></code>
1704                     </p>
1705                   </td>
1706 <td>
1707                     <p>
1708                       The filter returns <code class="computeroutput"><span class="keyword">true</span></code>
1709                       if an attribute value with name "Ratio" of one of
1710                       the <a class="link" href="utilities.html#log.detailed.utilities.predef_types" title="Predefined type sequences">floating
1711                       point types</a> is not found or it is not between 0 and
1712                       0.5.
1713                     </p>
1714                   </td>
1715 </tr>
1716 <tr>
1717 <td>
1718                     <p>
1719                       <code class="computeroutput"><span class="special">%</span><span class="identifier">Tag</span><span class="special">%</span> <span class="identifier">contains</span>
1720                       <span class="string">"net"</span> <span class="keyword">or</span>
1721                       <span class="special">%</span><span class="identifier">Tag</span><span class="special">%</span> <span class="identifier">contains</span>
1722                       <span class="string">"io"</span> <span class="keyword">and</span>
1723                       <span class="keyword">not</span> <span class="special">%</span><span class="identifier">StatFlow</span><span class="special">%</span></code>
1724                     </p>
1725                   </td>
1726 <td>
1727                     <p>
1728                       The filter returns <code class="computeroutput"><span class="keyword">true</span></code>
1729                       if an attribute value with name "Tag" is found and
1730                       contains words "net" or "io" and if an
1731                       attribute value "StatFlow" is not found. The "Tag"
1732                       attribute value must be of one of the <a class="link" href="utilities.html#log.detailed.utilities.predef_types" title="Predefined type sequences">string
1733                       types</a>, the "StatFlow" attribute value type
1734                       is not considered.
1735                     </p>
1736                   </td>
1737 </tr>
1738 </tbody>
1739 </table></div>
1740 </div>
1741 <br class="table-break"><p>
1742             The formatter string syntax is even simpler and pretty much resembles
1743             <a href="http://www.boost.org/doc/libs/release/libs/format/index.html" target="_top">Boost.Format</a>
1744             format string syntax. The string is interpreted as a template which can
1745             contain attribute names enclosed with percent signs ("%").
1746             The corresponding attribute values will replace these placeholders when
1747             the formatter is applied. The placeholder "%Message%" will
1748             be replaced with the log record text. For instance, the following formatter
1749             string:
1750           </p>
1751 <pre class="programlisting">[%TimeStamp%] *%Severity%* %Message%
1752 </pre>
1753 <p>
1754             will make log records look like this:
1755           </p>
1756 <pre class="programlisting">[2008-07-05 13:44:23] *0* Hello world
1757 </pre>
1758 <div class="note"><table border="0" summary="Note">
1759 <tr>
1760 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../doc/src/images/note.png"></td>
1761 <th align="left">Note</th>
1762 </tr>
1763 <tr><td align="left" valign="top"><p>
1764               Previous releases of the library also supported the "%_%"
1765               placeholder for the message text. This placeholder is deprecated now,
1766               although it still works for backward compatibility. Its support will
1767               be removed in future releases.
1768             </p></td></tr>
1769 </table></div>
1770 <p>
1771             It must be noted that by default the library only supports those attribute
1772             value types <a class="link" href="utilities.html#log.detailed.utilities.predef_types" title="Predefined type sequences">which
1773             are known</a> at the library build time. User-defined types will not
1774             work properly in parsed filters and formatters until registered in the
1775             library. It is also possible to override formatting rules of the known
1776             types, including support for additional formatting parameters in the
1777             string template. More on this is available in the <a class="link" href="../extension/settings.html" title="Extending library settings support">Extending
1778             the library</a> section.
1779           </p>
1780 <div class="note"><table border="0" summary="Note">
1781 <tr>
1782 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../doc/src/images/note.png"></td>
1783 <th align="left">Note</th>
1784 </tr>
1785 <tr><td align="left" valign="top"><p>
1786               The parsed formatters and filters are generally less optimal than the
1787               equivalent ones written in code with <a class="link" href="expressions.html" title="Lambda expressions">template
1788               expressions</a>. This is because of two reasons: (*) the programmer
1789               usually knows more about types of the attribute values that may be
1790               involved in formatting or filtering and (*) the compiler has a better
1791               chance to optimize the formatter or filter if it is known in compile
1792               time. Therefore, when performance matters, it is advised to avoid parsed
1793               filters and formatters.
1794             </p></td></tr>
1795 </table></div>
1796 </div>
1797 <div class="section">
1798 <div class="titlepage"><div><div><h5 class="title">
1799 <a name="log.detailed.utilities.setup.settings"></a><a class="link" href="utilities.html#log.detailed.utilities.setup.settings" title="Library initialization from a settings container">Library initialization
1800           from a settings container</a>
1801 </h5></div></div></div>
1802 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><code class="computeroutput"><a class="link" href="../../utilities.html#header.boost.log.utility.setup.settings_hpp" title="Header &lt;boost/log/utility/setup/settings.hpp&gt;">boost/log/utility/setup/settings.hpp</a></code><span class="special">&gt;</span>
1803 <span class="preprocessor">#include</span> <span class="special">&lt;</span><code class="computeroutput"><a class="link" href="../../utilities.html#header.boost.log.utility.setup.from_settings_hpp" title="Header &lt;boost/log/utility/setup/from_settings.hpp&gt;">boost/log/utility/setup/from_settings.hpp</a></code><span class="special">&gt;</span>
1804 </pre>
1805 <p>
1806             The headers define components for library initialization from a settings
1807             container. The settings container is basically a set of named parameters
1808             divided into sections. The container is implemented with the <code class="computeroutput"><a class="link" href="../../boost/log/basic_settings.html" title="Class template basic_settings">basic_settings</a></code> class template.
1809             There are several constraints on how parameters are stored in the container:
1810           </p>
1811 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1812 <li class="listitem">
1813                 Every parameter must reside in a section. There can be no parameters
1814                 that do not belong to a section.
1815               </li>
1816 <li class="listitem">
1817                 Parameters must have names unique within the section they belong
1818                 to. Parameters from different sections may have the same name.
1819               </li>
1820 <li class="listitem">
1821                 Sections can nest. When read from a file or accessed from the code,
1822                 section names can express arbitrary hierarchy by separating the parent
1823                 and child section names with '.' (e.g. "[Parent.Child.ChildChild]").
1824               </li>
1825 <li class="listitem">
1826                 Sections must have names unique within the enclosing section (or
1827                 global scope, if the section is top level).
1828               </li>
1829 </ul></div>
1830 <p>
1831             So basically, settings container is a layered associative container,
1832             with string keys and values. In some respect it is similar to <a href="http://www.boost.org/doc/libs/release/doc/html/property_tree.html" target="_top">Boost.PropertyTree</a>,
1833             and in fact it supports construction from <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">ptree</span></code>.
1834             The supported parameters are described below.
1835           </p>
1836 <div class="tip"><table border="0" summary="Tip">
1837 <tr>
1838 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../../../doc/src/images/tip.png"></td>
1839 <th align="left">Tip</th>
1840 </tr>
1841 <tr><td align="left" valign="top"><p>
1842               In the tables below, the <code class="computeroutput"><span class="identifier">CharT</span></code>
1843               type denotes the character type that is used with the settings container.
1844             </p></td></tr>
1845 </table></div>
1846 <div class="table">
1847 <a name="log.detailed.utilities.setup.settings.section__core___logging_core_settings_"></a><p class="title"><b>Table&#160;1.9.&#160;Section "Core". Logging core settings.</b></p>
1848 <div class="table-contents"><table class="table" summary='Section "Core". Logging core settings.'>
1849 <colgroup>
1850 <col>
1851 <col>
1852 <col>
1853 </colgroup>
1854 <thead><tr>
1855 <th>
1856                     <p>
1857                       Parameter
1858                     </p>
1859                   </th>
1860 <th>
1861                     <p>
1862                       Format
1863                     </p>
1864                   </th>
1865 <th>
1866                     <p>
1867                       Description
1868                     </p>
1869                   </th>
1870 </tr></thead>
1871 <tbody>
1872 <tr>
1873 <td>
1874                     <p>
1875                       Filter
1876                     </p>
1877                   </td>
1878 <td>
1879                     <p>
1880                       Filter string as described <a class="link" href="utilities.html#log.detailed.utilities.setup.filter_formatter" title="Filter and formatter parsers">here</a>
1881                     </p>
1882                   </td>
1883 <td>
1884                     <p>
1885                       Global filter to be installed to the core. If not specified,
1886                       the global filter is not set.
1887                     </p>
1888                   </td>
1889 </tr>
1890 <tr>
1891 <td>
1892                     <p>
1893                       DisableLogging
1894                     </p>
1895                   </td>
1896 <td>
1897                     <p>
1898                       "true" or "false"
1899                     </p>
1900                   </td>
1901 <td>
1902                     <p>
1903                       If <code class="computeroutput"><span class="keyword">true</span></code>, results
1904                       in calling <code class="computeroutput"><span class="identifier">set_logging_enabled</span><span class="special">(</span><span class="keyword">false</span><span class="special">)</span></code> on the core. By default, value
1905                       <code class="computeroutput"><span class="keyword">false</span></code> is assumed.
1906                     </p>
1907                   </td>
1908 </tr>
1909 </tbody>
1910 </table></div>
1911 </div>
1912 <br class="table-break"><p>
1913             Sink settings are divided into separate subsections within the common
1914             top-level section "Sinks" - one subsection for each sink. The
1915             subsection names denote a user-defined sink name. For example, "MyFile".
1916           </p>
1917 <div class="note"><table border="0" summary="Note">
1918 <tr>
1919 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../doc/src/images/note.png"></td>
1920 <th align="left">Note</th>
1921 </tr>
1922 <tr><td align="left" valign="top"><p>
1923               Previous versions of the library also supported top-level sections
1924               starting with the "Sink:" prefix to describe sink parameters.
1925               This syntax is deprecated now, although it still works when parsing
1926               a settings file for backward compatibility. The parser will automatically
1927               put these sections under the "Sinks" top-level section in
1928               the resulting settings container. Support for this syntax will be removed
1929               in future releases.
1930             </p></td></tr>
1931 </table></div>
1932 <div class="table">
1933 <a name="log.detailed.utilities.setup.settings.sections_under_the__sinks__section__common_sink_settings_"></a><p class="title"><b>Table&#160;1.10.&#160;Sections under the "Sinks" section. Common sink settings.</b></p>
1934 <div class="table-contents"><table class="table" summary='Sections under the "Sinks" section. Common sink settings.'>
1935 <colgroup>
1936 <col>
1937 <col>
1938 <col>
1939 </colgroup>
1940 <thead><tr>
1941 <th>
1942                     <p>
1943                       Parameter
1944                     </p>
1945                   </th>
1946 <th>
1947                     <p>
1948                       Format
1949                     </p>
1950                   </th>
1951 <th>
1952                     <p>
1953                       Description
1954                     </p>
1955                   </th>
1956 </tr></thead>
1957 <tbody>
1958 <tr>
1959 <td>
1960                     <p>
1961                       Destination
1962                     </p>
1963                   </td>
1964 <td>
1965                     <p>
1966                       Sink target, see description
1967                     </p>
1968                   </td>
1969 <td>
1970                     <p>
1971                       Sink backend type. Mandatory parameter. May have one of these
1972                       values: <a class="link" href="sink_backends.html#log.detailed.sink_backends.text_ostream" title="Text stream backend">Console</a>,
1973                       <a class="link" href="sink_backends.html#log.detailed.sink_backends.text_file" title="Text file backend">TextFile</a>,
1974                       <a class="link" href="sink_backends.html#log.detailed.sink_backends.syslog" title="Syslog backend">Syslog</a>.
1975                       On Windows the following values are additionally supported:
1976                       <a class="link" href="sink_backends.html#log.detailed.sink_backends.event_log" title="Windows event log backends">SimpleEventLog</a>,
1977                       <a class="link" href="sink_backends.html#log.detailed.sink_backends.debugger" title="Windows debugger output backend">Debugger</a>.
1978                       Also, user-defined sink names may also be supported if registered
1979                       by calling <code class="computeroutput"><a class="link" href="../../boost/log/register_idm45711342847040.html" title="Function template register_sink_factory">register_sink_factory</a></code>.
1980                       See <a class="link" href="../extension/settings.html#log.extension.settings.sinks" title="Adding support for user-defined sinks">this</a>
1981                       section on how to add support for new sinks.
1982                     </p>
1983                   </td>
1984 </tr>
1985 <tr>
1986 <td>
1987                     <p>
1988                       Filter
1989                     </p>
1990                   </td>
1991 <td>
1992                     <p>
1993                       Filter string as described <a class="link" href="utilities.html#log.detailed.utilities.setup.filter_formatter" title="Filter and formatter parsers">here</a>
1994                     </p>
1995                   </td>
1996 <td>
1997                     <p>
1998                       Sink-specific filter. If not specified, the filter is not set.
1999                     </p>
2000                   </td>
2001 </tr>
2002 <tr>
2003 <td>
2004                     <p>
2005                       Asynchronous
2006                     </p>
2007                   </td>
2008 <td>
2009                     <p>
2010                       "true" or "false"
2011                     </p>
2012                   </td>
2013 <td>
2014                     <p>
2015                       If <code class="computeroutput"><span class="keyword">true</span></code>, the
2016                       <a class="link" href="sink_frontends.html#log.detailed.sink_frontends.async" title="Asynchronous sink frontend">asynchronous
2017                       sink frontend</a> will be used. Otherwise the <a class="link" href="sink_frontends.html#log.detailed.sink_frontends.sync" title="Synchronous sink frontend">synchronous
2018                       sink frontend</a> will be used. By default, value <code class="computeroutput"><span class="keyword">false</span></code> is assumed. In single-threaded
2019                       builds this parameter is not used, as <a class="link" href="sink_frontends.html#log.detailed.sink_frontends.unlocked" title="Unlocked sink frontend">unlocked
2020                       sink frontend</a> is always used.
2021                     </p>
2022                   </td>
2023 </tr>
2024 </tbody>
2025 </table></div>
2026 </div>
2027 <br class="table-break"><p>
2028             Besides the common settings that all sinks support, some sink backends
2029             also accept a number of specific parameters. These parameters should
2030             be specified in the same section.
2031           </p>
2032 <div class="table">
2033 <a name="log.detailed.utilities.setup.settings._console__sink_settings"></a><p class="title"><b>Table&#160;1.11.&#160;"Console" sink settings</b></p>
2034 <div class="table-contents"><table class="table" summary='"Console" sink settings'>
2035 <colgroup>
2036 <col>
2037 <col>
2038 <col>
2039 </colgroup>
2040 <thead><tr>
2041 <th>
2042                     <p>
2043                       Parameter
2044                     </p>
2045                   </th>
2046 <th>
2047                     <p>
2048                       Format
2049                     </p>
2050                   </th>
2051 <th>
2052                     <p>
2053                       Description
2054                     </p>
2055                   </th>
2056 </tr></thead>
2057 <tbody>
2058 <tr>
2059 <td>
2060                     <p>
2061                       Format
2062                     </p>
2063                   </td>
2064 <td>
2065                     <p>
2066                       Format string as described <a class="link" href="utilities.html#log.detailed.utilities.setup.filter_formatter" title="Filter and formatter parsers">here</a>
2067                     </p>
2068                   </td>
2069 <td>
2070                     <p>
2071                       Log record formatter to be used by the sink. If not specified,
2072                       the default formatter is used.
2073                     </p>
2074                   </td>
2075 </tr>
2076 <tr>
2077 <td>
2078                     <p>
2079                       AutoNewline
2080                     </p>
2081                   </td>
2082 <td>
2083                     <p>
2084                       "Disabled", "AlwaysInsert" or "InsertIfMissing"
2085                     </p>
2086                   </td>
2087 <td>
2088                     <p>
2089                       Controls whether the backend should automatically insert a
2090                       trailing newline after every log record, see <code class="computeroutput"><a class="link" href="../../sinks.html#boost.log.sinks.auto_newline_mode">auto_newline_mode</a></code>.
2091                       If not specified, the default value is "InsertIfMissing".
2092                     </p>
2093                   </td>
2094 </tr>
2095 <tr>
2096 <td>
2097                     <p>
2098                       AutoFlush
2099                     </p>
2100                   </td>
2101 <td>
2102                     <p>
2103                       "true" or "false"
2104                     </p>
2105                   </td>
2106 <td>
2107                     <p>
2108                       Enables or disables the auto-flush feature of the backend.
2109                       If not specified, the default value <code class="computeroutput"><span class="keyword">false</span></code>
2110                       is assumed.
2111                     </p>
2112                   </td>
2113 </tr>
2114 </tbody>
2115 </table></div>
2116 </div>
2117 <br class="table-break"><div class="table">
2118 <a name="log.detailed.utilities.setup.settings._textfile__sink_settings"></a><p class="title"><b>Table&#160;1.12.&#160;"TextFile" sink settings</b></p>
2119 <div class="table-contents"><table class="table" summary='"TextFile" sink settings'>
2120 <colgroup>
2121 <col>
2122 <col>
2123 <col>
2124 </colgroup>
2125 <thead><tr>
2126 <th>
2127                     <p>
2128                       Parameter
2129                     </p>
2130                   </th>
2131 <th>
2132                     <p>
2133                       Format
2134                     </p>
2135                   </th>
2136 <th>
2137                     <p>
2138                       Description
2139                     </p>
2140                   </th>
2141 </tr></thead>
2142 <tbody>
2143 <tr>
2144 <td>
2145                     <p>
2146                       FileName
2147                     </p>
2148                   </td>
2149 <td>
2150                     <p>
2151                       File name pattern
2152                     </p>
2153                   </td>
2154 <td>
2155                     <p>
2156                       The active file name pattern for the sink backend. This parameter
2157                       is mandatory.
2158                     </p>
2159                   </td>
2160 </tr>
2161 <tr>
2162 <td>
2163                     <p>
2164                       TargetFileName
2165                     </p>
2166                   </td>
2167 <td>
2168                     <p>
2169                       File name pattern
2170                     </p>
2171                   </td>
2172 <td>
2173                     <p>
2174                       The target file name pattern for the sink backend. If not specified,
2175                       active file name is preserved after rotation.
2176                     </p>
2177                   </td>
2178 </tr>
2179 <tr>
2180 <td>
2181                     <p>
2182                       Format
2183                     </p>
2184                   </td>
2185 <td>
2186                     <p>
2187                       Format string as described <a class="link" href="utilities.html#log.detailed.utilities.setup.filter_formatter" title="Filter and formatter parsers">here</a>
2188                     </p>
2189                   </td>
2190 <td>
2191                     <p>
2192                       Log record formatter to be used by the sink. If not specified,
2193                       the default formatter is used.
2194                     </p>
2195                   </td>
2196 </tr>
2197 <tr>
2198 <td>
2199                     <p>
2200                       AutoNewline
2201                     </p>
2202                   </td>
2203 <td>
2204                     <p>
2205                       "Disabled", "AlwaysInsert" or "InsertIfMissing"
2206                     </p>
2207                   </td>
2208 <td>
2209                     <p>
2210                       Controls whether the backend should automatically insert a
2211                       trailing newline after every log record, see <code class="computeroutput"><a class="link" href="../../sinks.html#boost.log.sinks.auto_newline_mode">auto_newline_mode</a></code>.
2212                       If not specified, the default value is "InsertIfMissing".
2213                     </p>
2214                   </td>
2215 </tr>
2216 <tr>
2217 <td>
2218                     <p>
2219                       AutoFlush
2220                     </p>
2221                   </td>
2222 <td>
2223                     <p>
2224                       "true" or "false"
2225                     </p>
2226                   </td>
2227 <td>
2228                     <p>
2229                       Enables or disables the auto-flush feature of the backend.
2230                       If not specified, the default value <code class="computeroutput"><span class="keyword">false</span></code>
2231                       is assumed.
2232                     </p>
2233                   </td>
2234 </tr>
2235 <tr>
2236 <td>
2237                     <p>
2238                       Append
2239                     </p>
2240                   </td>
2241 <td>
2242                     <p>
2243                       "true" or "false"
2244                     </p>
2245                   </td>
2246 <td>
2247                     <p>
2248                       Enables or disables <a class="link" href="sink_backends.html#log.detailed.sink_backends.text_file.appending" title="Appending to the previously written files">appending</a>
2249                       to the existing file instead of overwriting it. If not specified,
2250                       the default value <code class="computeroutput"><span class="keyword">false</span></code>
2251                       is assumed.
2252                     </p>
2253                   </td>
2254 </tr>
2255 <tr>
2256 <td>
2257                     <p>
2258                       RotationSize
2259                     </p>
2260                   </td>
2261 <td>
2262                     <p>
2263                       Unsigned integer
2264                     </p>
2265                   </td>
2266 <td>
2267                     <p>
2268                       File size, in bytes, upon which <a class="link" href="sink_backends.html#log.detailed.sink_backends.text_file.file_rotation" title="File rotation">file
2269                       rotation</a> will be performed. If not specified, no size-based
2270                       rotation will be made.
2271                     </p>
2272                   </td>
2273 </tr>
2274 <tr>
2275 <td>
2276                     <p>
2277                       RotationInterval
2278                     </p>
2279                   </td>
2280 <td>
2281                     <p>
2282                       Unsigned integer
2283                     </p>
2284                   </td>
2285 <td>
2286                     <p>
2287                       Time interval, in seconds, upon which <a class="link" href="sink_backends.html#log.detailed.sink_backends.text_file.file_rotation" title="File rotation">file
2288                       rotation</a> will be performed. See also the RotationTimePoint
2289                       parameter and the note below.
2290                     </p>
2291                   </td>
2292 </tr>
2293 <tr>
2294 <td>
2295                     <p>
2296                       RotationTimePoint
2297                     </p>
2298                   </td>
2299 <td>
2300                     <p>
2301                       Time point format string, see below
2302                     </p>
2303                   </td>
2304 <td>
2305                     <p>
2306                       Time point or a predicate that detects at what moment of time
2307                       to perform log <a class="link" href="sink_backends.html#log.detailed.sink_backends.text_file.file_rotation" title="File rotation">file
2308                       rotation</a>. See also the RotationInterval parameter and
2309                       the note below.
2310                     </p>
2311                   </td>
2312 </tr>
2313 <tr>
2314 <td>
2315                     <p>
2316                       EnableFinalRotation
2317                     </p>
2318                   </td>
2319 <td>
2320                     <p>
2321                       "true" or "false"
2322                     </p>
2323                   </td>
2324 <td>
2325                     <p>
2326                       Enables or disables final file rotation on sink destruction,
2327                       which typically happens on program termination. If not specified,
2328                       the default value <code class="computeroutput"><span class="keyword">true</span></code>
2329                       is assumed.
2330                     </p>
2331                   </td>
2332 </tr>
2333 <tr>
2334 <td>
2335                     <p>
2336                       Target
2337                     </p>
2338                   </td>
2339 <td>
2340                     <p>
2341                       File system path to a directory
2342                     </p>
2343                   </td>
2344 <td>
2345                     <p>
2346                       Target directory name, in which the rotated files will be stored.
2347                       If this parameter is specified, rotated <a class="link" href="sink_backends.html#log.detailed.sink_backends.text_file.file_collection" title="Managing rotated files">file
2348                       collection</a> is enabled. Otherwise the feature is not
2349                       enabled and all corresponding parameters are ignored.
2350                     </p>
2351                   </td>
2352 </tr>
2353 <tr>
2354 <td>
2355                     <p>
2356                       MaxSize
2357                     </p>
2358                   </td>
2359 <td>
2360                     <p>
2361                       Unsigned integer
2362                     </p>
2363                   </td>
2364 <td>
2365                     <p>
2366                       Total size of files in the target directory, in bytes, upon
2367                       which the oldest file will be deleted. If not specified, no
2368                       size-based file cleanup will be performed.
2369                     </p>
2370                   </td>
2371 </tr>
2372 <tr>
2373 <td>
2374                     <p>
2375                       MinFreeSpace
2376                     </p>
2377                   </td>
2378 <td>
2379                     <p>
2380                       Unsigned integer
2381                     </p>
2382                   </td>
2383 <td>
2384                     <p>
2385                       Minimum free space in the target directory, in bytes, upon
2386                       which the oldest file will be deleted. If not specified, no
2387                       space-based file cleanup will be performed.
2388                     </p>
2389                   </td>
2390 </tr>
2391 <tr>
2392 <td>
2393                     <p>
2394                       MaxFiles
2395                     </p>
2396                   </td>
2397 <td>
2398                     <p>
2399                       Unsigned integer
2400                     </p>
2401                   </td>
2402 <td>
2403                     <p>
2404                       Total number of files in the target directory, upon which the
2405                       oldest file will be deleted. If not specified, no count-based
2406                       file cleanup will be performed.
2407                     </p>
2408                   </td>
2409 </tr>
2410 <tr>
2411 <td>
2412                     <p>
2413                       ScanForFiles
2414                     </p>
2415                   </td>
2416 <td>
2417                     <p>
2418                       "All" or "Matching"
2419                     </p>
2420                   </td>
2421 <td>
2422                     <p>
2423                       Mode of <a class="link" href="sink_backends.html#log.detailed.sink_backends.text_file.file_scanning" title="Scanning for rotated files">scanning</a>
2424                       for old files in the target directory, see <code class="computeroutput"><a class="link" href="../../sinks.html#boost.log.sinks.file.scan_method">scan_method</a></code>. If
2425                       not specified, no scanning will be performed.
2426                     </p>
2427                   </td>
2428 </tr>
2429 </tbody>
2430 </table></div>
2431 </div>
2432 <br class="table-break"><div class="warning"><table border="0" summary="Warning">
2433 <tr>
2434 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../../../doc/src/images/warning.png"></td>
2435 <th align="left">Warning</th>
2436 </tr>
2437 <tr><td align="left" valign="top"><p>
2438               The text file sink uses <a href="http://www.boost.org/doc/libs/release/libs/filesystem/doc/index.htm" target="_top">Boost.Filesystem</a>
2439               internally, which may cause problems on process termination. See <a class="link" href="../rationale/why_crash_on_term.html" title="Why my application crashes on process termination when file sinks are used?">here</a> for more details.
2440             </p></td></tr>
2441 </table></div>
2442 <p>
2443             The time-based rotation can be set up with one of the two parameters:
2444             RotationInterval or RotationTimePoint. Not more than one of these parameters
2445             should be specified for a given sink. If none is specified, no time-based
2446             rotation will be performed.
2447           </p>
2448 <p>
2449             The RotationTimePoint parameter should have one of the following formats,
2450             according to the <a href="http://www.boost.org/doc/libs/release/doc/html/date_time/date_time_io.html#date_time.format_flags" target="_top">Boost.DateTime</a>
2451             format notation:
2452           </p>
2453 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
2454 <li class="listitem">
2455                 "%H:%M:%S". In this case, file rotation will be performed
2456                 on a daily basis, at the specified time. For example, "12:00:00".
2457               </li>
2458 <li class="listitem">
2459                 "%a %H:%M:%S" or "%A %H:%M:%S". File rotation
2460                 takes place every week, on the weekday specified in the long or short
2461                 form, at the specified time. For example, "Saturday 09:00:00".
2462               </li>
2463 <li class="listitem">
2464                 "%d %H:%M:%S". File rotation takes place every month, on
2465                 the specified day of month, at the specified time. For example, "01
2466                 23:30:00".
2467               </li>
2468 </ul></div>
2469 <div class="table">
2470 <a name="log.detailed.utilities.setup.settings._syslog__sink_settings"></a><p class="title"><b>Table&#160;1.13.&#160;"Syslog" sink settings</b></p>
2471 <div class="table-contents"><table class="table" summary='"Syslog" sink settings'>
2472 <colgroup>
2473 <col>
2474 <col>
2475 <col>
2476 </colgroup>
2477 <thead><tr>
2478 <th>
2479                     <p>
2480                       Parameter
2481                     </p>
2482                   </th>
2483 <th>
2484                     <p>
2485                       Format
2486                     </p>
2487                   </th>
2488 <th>
2489                     <p>
2490                       Description
2491                     </p>
2492                   </th>
2493 </tr></thead>
2494 <tbody>
2495 <tr>
2496 <td>
2497                     <p>
2498                       Format
2499                     </p>
2500                   </td>
2501 <td>
2502                     <p>
2503                       Format string as described <a class="link" href="utilities.html#log.detailed.utilities.setup.filter_formatter" title="Filter and formatter parsers">here</a>
2504                     </p>
2505                   </td>
2506 <td>
2507                     <p>
2508                       Log record formatter to be used by the sink. If not specified,
2509                       the default formatter is used.
2510                     </p>
2511                   </td>
2512 </tr>
2513 <tr>
2514 <td>
2515                     <p>
2516                       LocalAddress
2517                     </p>
2518                   </td>
2519 <td>
2520                     <p>
2521                       An IP address
2522                     </p>
2523                   </td>
2524 <td>
2525                     <p>
2526                       Local address to initiate connection to the syslog server.
2527                       If not specified, the default local address will be used.
2528                     </p>
2529                   </td>
2530 </tr>
2531 <tr>
2532 <td>
2533                     <p>
2534                       TargetAddress
2535                     </p>
2536                   </td>
2537 <td>
2538                     <p>
2539                       An IP address
2540                     </p>
2541                   </td>
2542 <td>
2543                     <p>
2544                       Remote address of the syslog server. If not specified, the
2545                       local address will be used.
2546                     </p>
2547                   </td>
2548 </tr>
2549 </tbody>
2550 </table></div>
2551 </div>
2552 <br class="table-break"><div class="table">
2553 <a name="log.detailed.utilities.setup.settings._simpleeventlog__sink_settings"></a><p class="title"><b>Table&#160;1.14.&#160;"SimpleEventLog" sink settings</b></p>
2554 <div class="table-contents"><table class="table" summary='"SimpleEventLog" sink settings'>
2555 <colgroup>
2556 <col>
2557 <col>
2558 <col>
2559 </colgroup>
2560 <thead><tr>
2561 <th>
2562                     <p>
2563                       Parameter
2564                     </p>
2565                   </th>
2566 <th>
2567                     <p>
2568                       Format
2569                     </p>
2570                   </th>
2571 <th>
2572                     <p>
2573                       Description
2574                     </p>
2575                   </th>
2576 </tr></thead>
2577 <tbody>
2578 <tr>
2579 <td>
2580                     <p>
2581                       Format
2582                     </p>
2583                   </td>
2584 <td>
2585                     <p>
2586                       Format string as described <a class="link" href="utilities.html#log.detailed.utilities.setup.filter_formatter" title="Filter and formatter parsers">here</a>
2587                     </p>
2588                   </td>
2589 <td>
2590                     <p>
2591                       Log record formatter to be used by the sink. If not specified,
2592                       the default formatter is used.
2593                     </p>
2594                   </td>
2595 </tr>
2596 <tr>
2597 <td>
2598                     <p>
2599                       LogName
2600                     </p>
2601                   </td>
2602 <td>
2603                     <p>
2604                       A string
2605                     </p>
2606                   </td>
2607 <td>
2608                     <p>
2609                       Log name to write events into. If not specified, the default
2610                       log name will be used.
2611                     </p>
2612                   </td>
2613 </tr>
2614 <tr>
2615 <td>
2616                     <p>
2617                       LogSource
2618                     </p>
2619                   </td>
2620 <td>
2621                     <p>
2622                       A string
2623                     </p>
2624                   </td>
2625 <td>
2626                     <p>
2627                       Log source to write events from. If not specified, the default
2628                       source will be used.
2629                     </p>
2630                   </td>
2631 </tr>
2632 <tr>
2633 <td>
2634                     <p>
2635                       Registration
2636                     </p>
2637                   </td>
2638 <td>
2639                     <p>
2640                       "Never", "OnDemand" or "Forced"
2641                     </p>
2642                   </td>
2643 <td>
2644                     <p>
2645                       Mode of log source registration in Windows registry, see <code class="computeroutput"><a class="link" href="../../sinks.html#boost.log.sinks.event_log.registration_mode">registration_mode</a></code>.
2646                       If not specified, on-demand registration will be performed.
2647                     </p>
2648                   </td>
2649 </tr>
2650 </tbody>
2651 </table></div>
2652 </div>
2653 <br class="table-break"><p>
2654             The user is free to fill the settings container from whatever settings
2655             source he needs. The usage example is below:
2656           </p>
2657 <p>
2658 </p>
2659 <pre class="programlisting"><span class="identifier">logging</span><span class="special">::</span><span class="identifier">settings</span> <span class="identifier">setts</span><span class="special">;</span>
2660
2661 <span class="identifier">setts</span><span class="special">[</span><span class="string">"Core"</span><span class="special">][</span><span class="string">"Filter"</span><span class="special">]</span> <span class="special">=</span> <span class="string">"%Severity% &gt;= warning"</span><span class="special">;</span>
2662 <span class="identifier">setts</span><span class="special">[</span><span class="string">"Core"</span><span class="special">][</span><span class="string">"DisableLogging"</span><span class="special">]</span> <span class="special">=</span> <span class="keyword">false</span><span class="special">;</span>
2663
2664 <span class="comment">// Subsections can be referred to with a single path</span>
2665 <span class="identifier">setts</span><span class="special">[</span><span class="string">"Sinks.Console"</span><span class="special">][</span><span class="string">"Destination"</span><span class="special">]</span> <span class="special">=</span> <span class="string">"Console"</span><span class="special">;</span>
2666 <span class="identifier">setts</span><span class="special">[</span><span class="string">"Sinks.Console"</span><span class="special">][</span><span class="string">"Filter"</span><span class="special">]</span> <span class="special">=</span> <span class="string">"%Severity% &gt;= critical"</span><span class="special">;</span>
2667 <span class="identifier">setts</span><span class="special">[</span><span class="string">"Sinks.Console"</span><span class="special">][</span><span class="string">"Format"</span><span class="special">]</span> <span class="special">=</span> <span class="string">"%TimeStamp% [%Severity%] %Message%"</span><span class="special">;</span>
2668 <span class="identifier">setts</span><span class="special">[</span><span class="string">"Sinks.Console"</span><span class="special">][</span><span class="string">"AutoFlush"</span><span class="special">]</span> <span class="special">=</span> <span class="keyword">true</span><span class="special">;</span>
2669
2670 <span class="comment">// ...as well as the individual parameters</span>
2671 <span class="identifier">setts</span><span class="special">[</span><span class="string">"Sinks.File.Destination"</span><span class="special">]</span> <span class="special">=</span> <span class="string">"TextFile"</span><span class="special">;</span>
2672 <span class="identifier">setts</span><span class="special">[</span><span class="string">"Sinks.File.FileName"</span><span class="special">]</span> <span class="special">=</span> <span class="string">"MyApp_%3N.log"</span><span class="special">;</span>
2673 <span class="identifier">setts</span><span class="special">[</span><span class="string">"Sinks.File.AutoFlush"</span><span class="special">]</span> <span class="special">=</span> <span class="keyword">true</span><span class="special">;</span>
2674 <span class="identifier">setts</span><span class="special">[</span><span class="string">"Sinks.File.RotationSize"</span><span class="special">]</span> <span class="special">=</span> <span class="number">10</span> <span class="special">*</span> <span class="number">1024</span> <span class="special">*</span> <span class="number">1024</span><span class="special">;</span> <span class="comment">// 10 MiB</span>
2675 <span class="identifier">setts</span><span class="special">[</span><span class="string">"Sinks.File.Format"</span><span class="special">]</span> <span class="special">=</span> <span class="string">"%TimeStamp% [%Severity%] %Message%"</span><span class="special">;</span>
2676
2677 <span class="identifier">logging</span><span class="special">::</span><span class="identifier">init_from_settings</span><span class="special">(</span><span class="identifier">setts</span><span class="special">);</span>
2678 </pre>
2679 <p>
2680           </p>
2681 <p>
2682             <a href="../../../../../../libs/log/example/doc/util_setup_settings.cpp" target="_top">See
2683             the complete code</a>.
2684           </p>
2685 <div class="note"><table border="0" summary="Note">
2686 <tr>
2687 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../doc/src/images/note.png"></td>
2688 <th align="left">Note</th>
2689 </tr>
2690 <tr><td align="left" valign="top"><p>
2691               Initialization from settings does not automatically create any attributes
2692               or loggers, the application developer is still responsible for creating
2693               those. It can be said that loggers and attributes define the data that
2694               is exported by the application and the settings only describe how that
2695               data is going to be presented to the application user.
2696             </p></td></tr>
2697 </table></div>
2698 <p>
2699             The settings reader also can be extended to support custom sink types.
2700             See the <a class="link" href="../extension/settings.html" title="Extending library settings support">Extending the library</a>
2701             section for more information.
2702           </p>
2703 </div>
2704 <div class="section">
2705 <div class="titlepage"><div><div><h5 class="title">
2706 <a name="log.detailed.utilities.setup.settings_file"></a><a class="link" href="utilities.html#log.detailed.utilities.setup.settings_file" title="Library initialization from a settings file">Library
2707           initialization from a settings file</a>
2708 </h5></div></div></div>
2709 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><code class="computeroutput"><a class="link" href="../../utilities.html#header.boost.log.utility.setup.from_stream_hpp" title="Header &lt;boost/log/utility/setup/from_stream.hpp&gt;">boost/log/utility/setup/from_stream.hpp</a></code><span class="special">&gt;</span>
2710 </pre>
2711 <p>
2712             Support for configuration files is a frequently requested feature of
2713             the library. And despite the fact there is no ultimately convenient and
2714             flexible format of the library settings, the library provides preliminary
2715             support for this feature. The functionality is implemented with a simple
2716             function <code class="computeroutput"><a class="link" href="../../boost/log/init_from_stream.html" title="Function template init_from_stream">init_from_stream</a></code>, which
2717             accepts a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">istream</span></code> and reads the library settings
2718             from it. The function then passes on the read settings to the <code class="computeroutput"><a class="link" href="../../boost/log/init_from_settings.html" title="Function template init_from_settings">init_from_settings</a></code>
2719             function, described <a class="link" href="utilities.html#log.detailed.utilities.setup.settings" title="Library initialization from a settings container">above</a>.
2720             Therefore the parameter names and their meaning is the same as for the
2721             <code class="computeroutput"><a class="link" href="../../boost/log/init_from_settings.html" title="Function template init_from_settings">init_from_settings</a></code>
2722             function.
2723           </p>
2724 <p>
2725             The settings format is quite simple and widely used. Below is the description
2726             of syntax and parameters.
2727           </p>
2728 <pre class="programlisting"># Comments are allowed. Comment line begins with the '#' character
2729 # and spans until the end of the line.
2730
2731 # Logging core settings section. May be omitted if no parameters specified within it.
2732 [Core]
2733 DisableLogging=false
2734 Filter="%Severity% &gt; 3"
2735
2736 # Sink settings sections
2737 [Sinks.MySink1]
2738
2739 # Sink destination type
2740 Destination=Console
2741
2742 # Sink-specific filter. Optional, by default no filter is applied.
2743 Filter="%Target% contains \"MySink1\""
2744
2745 # Formatter string. Optional, by default only log record message text is written.
2746 Format="&lt;%TimeStamp%&gt; - %Message%"
2747
2748 # The flag shows whether the sink should be asynchronous
2749 Asynchronous=false
2750
2751 # Enables automatic stream flush after each log record.
2752 AutoFlush=true
2753 </pre>
2754 <p>
2755             Here's the usage example:
2756           </p>
2757 <pre class="programlisting"><span class="keyword">int</span> <span class="identifier">main</span><span class="special">(</span><span class="keyword">int</span><span class="special">,</span> <span class="keyword">char</span><span class="special">*[])</span>
2758 <span class="special">{</span>
2759     <span class="comment">// Read logging settings from a file</span>
2760     <span class="identifier">std</span><span class="special">::</span><span class="identifier">ifstream</span> <span class="identifier">file</span><span class="special">(</span><span class="string">"settings.ini"</span><span class="special">);</span>
2761     <span class="identifier">logging</span><span class="special">::</span><span class="identifier">init_from_stream</span><span class="special">(</span><span class="identifier">file</span><span class="special">);</span>
2762
2763     <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
2764 <span class="special">}</span>
2765 </pre>
2766 <p>
2767             See a <a href="../../../../../../libs/log/example/settings_file/main.cpp" target="_top">more
2768             complete example</a>.
2769           </p>
2770 </div>
2771 </div>
2772 </div>
2773 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
2774 <td align="left"></td>
2775 <td align="right"><div class="copyright-footer">Copyright &#169; 2007-2016 Andrey Semashev<p>
2776         Distributed under the Boost Software License, Version 1.0. (See accompanying
2777         file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>).
2778       </p>
2779 </div></td>
2780 </tr></table>
2781 <hr>
2782 <div class="spirit-nav">
2783 <a accesskey="p" href="attributes.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../detailed.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../extension.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
2784 </div>
2785 </body>
2786 </html>