libs/log/doc/html/log/detailed/sources.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Logging sources</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="../detailed.html" title="Detailed features description">
  10 <link rel="next" href="sink_frontends.html" title="Sink frontends">
  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="../detailed.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="sink_frontends.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.sources"></a><a class="link" href="sources.html" title="Logging sources">Logging sources</a>
  21 </h3></div></div></div>
  22 <div class="toc"><dl class="toc">
  23 <dt><span class="section"><a href="sources.html#log.detailed.sources.basic_logger">Basic loggers</a></span></dt>
  24 <dt><span class="section"><a href="sources.html#log.detailed.sources.severity_level_logger">Loggers
  25         with severity level support</a></span></dt>
  26 <dt><span class="section"><a href="sources.html#log.detailed.sources.channel_logger">Loggers with channel
  27         support</a></span></dt>
  28 <dt><span class="section"><a href="sources.html#log.detailed.sources.exception_handling">Loggers with
  29         exception handling support</a></span></dt>
  30 <dt><span class="section"><a href="sources.html#log.detailed.sources.mixed_loggers">Loggers with mixed
  31         features</a></span></dt>
  32 <dt><span class="section"><a href="sources.html#log.detailed.sources.global_storage">Global storage
  33         for loggers</a></span></dt>
  34 </dl></div>
  35 <div class="section">
  36 <div class="titlepage"><div><div><h4 class="title">
  37 <a name="log.detailed.sources.basic_logger"></a><a class="link" href="sources.html#log.detailed.sources.basic_logger" title="Basic loggers">Basic loggers</a>
  38 </h4></div></div></div>
  39 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><code class="computeroutput"><a class="link" href="../../logging_sources.html#header.boost.log.sources.basic_logger_hpp" title="Header &lt;boost/log/sources/basic_logger.hpp&gt;">boost/log/sources/basic_logger.hpp</a></code><span class="special">&gt;</span>
  40 </pre>
  41 <p>
  42           The simplest logging sources provided by the library are loggers <code class="computeroutput"><a class="link" href="../../boost/log/sources/logger.html" title="Class logger">logger</a></code> and its thread-safe
  43           version, <code class="computeroutput"><a class="link" href="../../boost/log/sources/logger_mt.html" title="Class logger_mt">logger_mt</a></code>
  44           (<code class="computeroutput"><a class="link" href="../../boost/log/sources/wlogger.html" title="Class wlogger">wlogger</a></code> and
  45           <code class="computeroutput"><a class="link" href="../../boost/log/sources/wlogger_mt.html" title="Class wlogger_mt">wlogger_mt</a></code>
  46           for wide-character logging, accordingly). These loggers only provide the
  47           ability to store source-specific attributes within themselves and, of course,
  48           to form log records. This type of logger should probably be used when there
  49           is no need for advanced features like severity level checks. It may well
  50           be used as a tool to collect application statistics and register application
  51           events, such as notifications and alarms. In such cases the logger is normally
  52           used in conjunction with <a class="link" href="attributes.html#log.detailed.attributes.related_components.scoped_attributes" title="Scoped attributes">scoped
  53           attributes</a> to attach the needed data to the notification event.
  54           Below is an example of usage:
  55         </p>
  56 <p>
  57 </p>
  58 <pre class="programlisting"><span class="keyword">class</span> <span class="identifier">network_connection</span>
  59 <span class="special">{</span>
  60     <span class="identifier">src</span><span class="special">::</span><span class="identifier">logger</span> <span class="identifier">m_logger</span><span class="special">;</span>
  61     <span class="identifier">logging</span><span class="special">::</span><span class="identifier">attribute_set</span><span class="special">::</span><span class="identifier">iterator</span> <span class="identifier">m_remote_addr</span><span class="special">;</span>
  62
  63 <span class="keyword">public</span><span class="special">:</span>
  64     <span class="keyword">void</span> <span class="identifier">on_connected</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">remote_addr</span><span class="special">)</span>
  65     <span class="special">{</span>
  66         <span class="comment">// Put the remote address into the logger to automatically attach it</span>
  67         <span class="comment">// to every log record written through the logger</span>
  68         <span class="identifier">m_remote_addr</span> <span class="special">=</span> <span class="identifier">m_logger</span><span class="special">.</span><span class="identifier">add_attribute</span><span class="special">(</span><span class="string">"RemoteAddress"</span><span class="special">,</span>
  69             <span class="identifier">attrs</span><span class="special">::</span><span class="identifier">constant</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="identifier">remote_addr</span><span class="special">)).</span><span class="identifier">first</span><span class="special">;</span>
  70
  71         <span class="comment">// The straightforward way of logging</span>
  72         <span class="keyword">if</span> <span class="special">(</span><span class="identifier">logging</span><span class="special">::</span><span class="identifier">record</span> <span class="identifier">rec</span> <span class="special">=</span> <span class="identifier">m_logger</span><span class="special">.</span><span class="identifier">open_record</span><span class="special">())</span>
  73         <span class="special">{</span>
  74             <span class="identifier">rec</span><span class="special">.</span><span class="identifier">attribute_values</span><span class="special">().</span><span class="identifier">insert</span><span class="special">(</span><span class="string">"Message"</span><span class="special">,</span>
  75                 <span class="identifier">attrs</span><span class="special">::</span><span class="identifier">make_attribute_value</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="string">"Connection established"</span><span class="special">)));</span>
  76             <span class="identifier">m_logger</span><span class="special">.</span><span class="identifier">push_record</span><span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">move</span><span class="special">(</span><span class="identifier">rec</span><span class="special">));</span>
  77         <span class="special">}</span>
  78     <span class="special">}</span>
  79     <span class="keyword">void</span> <span class="identifier">on_disconnected</span><span class="special">()</span>
  80     <span class="special">{</span>
  81         <span class="comment">// The simpler way of logging: the above "if" condition is wrapped into a neat macro</span>
  82         <span class="identifier">BOOST_LOG</span><span class="special">(</span><span class="identifier">m_logger</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="string">"Connection shut down"</span><span class="special">;</span>
  83
  84         <span class="comment">// Remove the attribute with the remote address</span>
  85         <span class="identifier">m_logger</span><span class="special">.</span><span class="identifier">remove_attribute</span><span class="special">(</span><span class="identifier">m_remote_addr</span><span class="special">);</span>
  86     <span class="special">}</span>
  87     <span class="keyword">void</span> <span class="identifier">on_data_received</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">size</span><span class="special">)</span>
  88     <span class="special">{</span>
  89         <span class="comment">// Put the size as an additional attribute</span>
  90         <span class="comment">// so it can be collected and accumulated later if needed.</span>
  91         <span class="comment">// The attribute will be attached only to this log record.</span>
  92         <span class="identifier">BOOST_LOG</span><span class="special">(</span><span class="identifier">m_logger</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">"ReceivedSize"</span><span class="special">,</span> <span class="identifier">size</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="string">"Some data received"</span><span class="special">;</span>
  93     <span class="special">}</span>
  94     <span class="keyword">void</span> <span class="identifier">on_data_sent</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">size</span><span class="special">)</span>
  95     <span class="special">{</span>
  96         <span class="identifier">BOOST_LOG</span><span class="special">(</span><span class="identifier">m_logger</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">"SentSize"</span><span class="special">,</span> <span class="identifier">size</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="string">"Some data sent"</span><span class="special">;</span>
  97     <span class="special">}</span>
  98 <span class="special">};</span>
  99 </pre>
 100 <p>
 101         </p>
 102 <p>
 103           The class <code class="computeroutput"><span class="identifier">network_connection</span></code>
 104           in the code snippet above represents an approach to implementing simple
 105           logging and statistical information gathering in a network-related application.
 106           Each of the presented methods of the class effectively marks a corresponding
 107           event that can be tracked and collected on the sinks level. Furthermore,
 108           other methods of the class, that are not shown here for simplicity, are
 109           able to write logs too. Note that every log record ever made in the connected
 110           state of the <code class="computeroutput"><span class="identifier">network_connection</span></code>
 111           object will be implicitly marked up with the address of the remote site.
 112         </p>
 113 </div>
 114 <div class="section">
 115 <div class="titlepage"><div><div><h4 class="title">
 116 <a name="log.detailed.sources.severity_level_logger"></a><a class="link" href="sources.html#log.detailed.sources.severity_level_logger" title="Loggers with severity level support">Loggers
 117         with severity level support</a>
 118 </h4></div></div></div>
 119 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><code class="computeroutput"><a class="link" href="../../logging_sources.html#header.boost.log.sources.severity_feature_hpp" title="Header &lt;boost/log/sources/severity_feature.hpp&gt;">boost/log/sources/severity_feature.hpp</a></code><span class="special">&gt;</span>
 120 <span class="preprocessor">#include</span> <span class="special">&lt;</span><code class="computeroutput"><a class="link" href="../../logging_sources.html#header.boost.log.sources.severity_logger_hpp" title="Header &lt;boost/log/sources/severity_logger.hpp&gt;">boost/log/sources/severity_logger.hpp</a></code><span class="special">&gt;</span>
 121 </pre>
 122 <p>
 123           The ability to distinguish some log records from others based on some kind
 124           of level of severity or importance is one of the most frequently requested
 125           features. The class templates <code class="computeroutput"><a class="link" href="../../boost/log/sources/severity_logger.html" title="Class template severity_logger">severity_logger</a></code>
 126           and <code class="computeroutput"><a class="link" href="../../boost/log/sources/severity_logger_mt.html" title="Class template severity_logger_mt">severity_logger_mt</a></code>
 127           (along with their <code class="computeroutput"><a class="link" href="../../boost/log/sources/wseverity_logger.html" title="Class template wseverity_logger">wseverity_logger</a></code>
 128           and <code class="computeroutput"><a class="link" href="../../boost/log/sources/wseverity_logger_mt.html" title="Class template wseverity_logger_mt">wseverity_logger_mt</a></code>
 129           wide-character counterparts) provide this functionality.
 130         </p>
 131 <p>
 132           The loggers automatically register a special source-specific attribute
 133           "Severity", which can be set for every record in a compact and
 134           efficient manner, with a named argument <code class="computeroutput"><span class="identifier">severity</span></code>
 135           that can be passed to the constructor and/or the <code class="computeroutput"><span class="identifier">open_record</span></code>
 136           method. If passed to the logger constructor, the <code class="computeroutput"><span class="identifier">severity</span></code>
 137           argument sets the default value of the severity level that will be used
 138           if none is provided in the <code class="computeroutput"><span class="identifier">open_record</span></code>
 139           arguments. The <code class="computeroutput"><span class="identifier">severity</span></code>
 140           argument passed to the <code class="computeroutput"><span class="identifier">open_record</span></code>
 141           method sets the level of the particular log record being made. The type
 142           of the severity level can be provided as a template argument for the logger
 143           class template. The default type is <code class="computeroutput"><span class="keyword">int</span></code>.
 144         </p>
 145 <p>
 146           The actual values of this attribute and their meaning are entirely user-defined.
 147           However, it is recommended to use the level of value equivalent to zero
 148           as a base point for other values. This is because the default-constructed
 149           logger object sets its default severity level to zero. It is also recommended
 150           to define the same levels of severity for the entire application in order
 151           to avoid confusion in the written logs later. The following code snippet
 152           shows the usage of <code class="computeroutput"><span class="identifier">severity_logger</span></code>.
 153         </p>
 154 <p>
 155 </p>
 156 <pre class="programlisting"><span class="comment">// We define our own severity levels</span>
 157 <span class="keyword">enum</span> <span class="identifier">severity_level</span>
 158 <span class="special">{</span>
 159     <span class="identifier">normal</span><span class="special">,</span>
 160     <span class="identifier">notification</span><span class="special">,</span>
 161     <span class="identifier">warning</span><span class="special">,</span>
 162     <span class="identifier">error</span><span class="special">,</span>
 163     <span class="identifier">critical</span>
 164 <span class="special">};</span>
 165
 166 <span class="keyword">void</span> <span class="identifier">logging_function</span><span class="special">()</span>
 167 <span class="special">{</span>
 168     <span class="comment">// The logger implicitly adds a source-specific attribute 'Severity'</span>
 169     <span class="comment">// of type 'severity_level' on construction</span>
 170     <span class="identifier">src</span><span class="special">::</span><span class="identifier">severity_logger</span><span class="special">&lt;</span> <span class="identifier">severity_level</span> <span class="special">&gt;</span> <span class="identifier">slg</span><span class="special">;</span>
 171
 172     <span class="identifier">BOOST_LOG_SEV</span><span class="special">(</span><span class="identifier">slg</span><span class="special">,</span> <span class="identifier">normal</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="string">"A regular message"</span><span class="special">;</span>
 173     <span class="identifier">BOOST_LOG_SEV</span><span class="special">(</span><span class="identifier">slg</span><span class="special">,</span> <span class="identifier">warning</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="string">"Something bad is going on but I can handle it"</span><span class="special">;</span>
 174     <span class="identifier">BOOST_LOG_SEV</span><span class="special">(</span><span class="identifier">slg</span><span class="special">,</span> <span class="identifier">critical</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="string">"Everything crumbles, shoot me now!"</span><span class="special">;</span>
 175 <span class="special">}</span>
 176 </pre>
 177 <p>
 178         </p>
 179 <p>
 180 </p>
 181 <pre class="programlisting"><span class="keyword">void</span> <span class="identifier">default_severity</span><span class="special">()</span>
 182 <span class="special">{</span>
 183     <span class="comment">// The default severity can be specified in constructor.</span>
 184     <span class="identifier">src</span><span class="special">::</span><span class="identifier">severity_logger</span><span class="special">&lt;</span> <span class="identifier">severity_level</span> <span class="special">&gt;</span> <span class="identifier">error_lg</span><span class="special">(</span><span class="identifier">keywords</span><span class="special">::</span><span class="identifier">severity</span> <span class="special">=</span> <span class="identifier">error</span><span class="special">);</span>
 185
 186     <span class="identifier">BOOST_LOG</span><span class="special">(</span><span class="identifier">error_lg</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="string">"An error level log record (by default)"</span><span class="special">;</span>
 187
 188     <span class="comment">// The explicitly specified level overrides the default</span>
 189     <span class="identifier">BOOST_LOG_SEV</span><span class="special">(</span><span class="identifier">error_lg</span><span class="special">,</span> <span class="identifier">warning</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="string">"A warning level log record (overrode the default)"</span><span class="special">;</span>
 190 <span class="special">}</span>
 191 </pre>
 192 <p>
 193         </p>
 194 <p>
 195           Or, if you prefer logging without macros:
 196         </p>
 197 <p>
 198 </p>
 199 <pre class="programlisting"><span class="keyword">void</span> <span class="identifier">manual_logging</span><span class="special">()</span>
 200 <span class="special">{</span>
 201     <span class="identifier">src</span><span class="special">::</span><span class="identifier">severity_logger</span><span class="special">&lt;</span> <span class="identifier">severity_level</span> <span class="special">&gt;</span> <span class="identifier">slg</span><span class="special">;</span>
 202
 203     <span class="identifier">logging</span><span class="special">::</span><span class="identifier">record</span> <span class="identifier">rec</span> <span class="special">=</span> <span class="identifier">slg</span><span class="special">.</span><span class="identifier">open_record</span><span class="special">(</span><span class="identifier">keywords</span><span class="special">::</span><span class="identifier">severity</span> <span class="special">=</span> <span class="identifier">normal</span><span class="special">);</span>
 204     <span class="keyword">if</span> <span class="special">(</span><span class="identifier">rec</span><span class="special">)</span>
 205     <span class="special">{</span>
 206         <span class="identifier">logging</span><span class="special">::</span><span class="identifier">record_ostream</span> <span class="identifier">strm</span><span class="special">(</span><span class="identifier">rec</span><span class="special">);</span>
 207         <span class="identifier">strm</span> <span class="special">&lt;&lt;</span> <span class="string">"A regular message"</span><span class="special">;</span>
 208         <span class="identifier">strm</span><span class="special">.</span><span class="identifier">flush</span><span class="special">();</span>
 209         <span class="identifier">slg</span><span class="special">.</span><span class="identifier">push_record</span><span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">move</span><span class="special">(</span><span class="identifier">rec</span><span class="special">));</span>
 210     <span class="special">}</span>
 211 <span class="special">}</span>
 212 </pre>
 213 <p>
 214         </p>
 215 <p>
 216           And, of course, severity loggers also provide the same functionality the
 217           <a class="link" href="sources.html#log.detailed.sources.basic_logger" title="Basic loggers">basic loggers</a>
 218           do.
 219         </p>
 220 </div>
 221 <div class="section">
 222 <div class="titlepage"><div><div><h4 class="title">
 223 <a name="log.detailed.sources.channel_logger"></a><a class="link" href="sources.html#log.detailed.sources.channel_logger" title="Loggers with channel support">Loggers with channel
 224         support</a>
 225 </h4></div></div></div>
 226 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><code class="computeroutput"><a class="link" href="../../logging_sources.html#header.boost.log.sources.channel_feature_hpp" title="Header &lt;boost/log/sources/channel_feature.hpp&gt;">boost/log/sources/channel_feature.hpp</a></code><span class="special">&gt;</span>
 227 <span class="preprocessor">#include</span> <span class="special">&lt;</span><code class="computeroutput"><a class="link" href="../../logging_sources.html#header.boost.log.sources.channel_logger_hpp" title="Header &lt;boost/log/sources/channel_logger.hpp&gt;">boost/log/sources/channel_logger.hpp</a></code><span class="special">&gt;</span>
 228 </pre>
 229 <p>
 230           Sometimes it is important to associate log records with some application
 231           component, such as the module or class name, the relation of the logged
 232           information to some specific domain of application functionality (e.g.
 233           network or file system related messages) or some arbitrary tag that can
 234           be used later to route these records to a specific sink. This feature is
 235           fulfilled with loggers <code class="computeroutput"><a class="link" href="../../boost/log/sources/channel_logger.html" title="Class template channel_logger">channel_logger</a></code>,
 236           <code class="computeroutput"><a class="link" href="../../boost/log/sources/channel_logger_mt.html" title="Class template channel_logger_mt">channel_logger_mt</a></code>
 237           and their wide-char counterparts <code class="computeroutput"><a class="link" href="../../boost/log/sources/wchannel_logger.html" title="Class template wchannel_logger">wchannel_logger</a></code>,
 238           <code class="computeroutput"><a class="link" href="../../boost/log/sources/wchannel_logger_mt.html" title="Class template wchannel_logger_mt">wchannel_logger_mt</a></code>.
 239           These loggers automatically register an attribute named "Channel".
 240           The default channel name can be set in the logger constructor with a named
 241           argument <code class="computeroutput"><span class="identifier">channel</span></code>. The type
 242           of the channel attribute value can be specified as a template argument
 243           for the logger, with <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span></code>
 244           (<code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">wstring</span></code> in case of wide character loggers)
 245           as a default. Aside from that, the usage is similar to the <a class="link" href="sources.html#log.detailed.sources.basic_logger" title="Basic loggers">basic
 246           loggers</a>:
 247         </p>
 248 <p>
 249 </p>
 250 <pre class="programlisting"><span class="keyword">class</span> <span class="identifier">network_connection</span>
 251 <span class="special">{</span>
 252     <span class="identifier">src</span><span class="special">::</span><span class="identifier">channel_logger</span><span class="special">&lt;</span> <span class="special">&gt;</span> <span class="identifier">m_net</span><span class="special">,</span> <span class="identifier">m_stat</span><span class="special">;</span>
 253     <span class="identifier">logging</span><span class="special">::</span><span class="identifier">attribute_set</span><span class="special">::</span><span class="identifier">iterator</span> <span class="identifier">m_net_remote_addr</span><span class="special">,</span> <span class="identifier">m_stat_remote_addr</span><span class="special">;</span>
 254
 255 <span class="keyword">public</span><span class="special">:</span>
 256     <span class="identifier">network_connection</span><span class="special">()</span> <span class="special">:</span>
 257         <span class="comment">// We can dump network-related messages through this logger</span>
 258         <span class="comment">// and be able to filter them later</span>
 259         <span class="identifier">m_net</span><span class="special">(</span><span class="identifier">keywords</span><span class="special">::</span><span class="identifier">channel</span> <span class="special">=</span> <span class="string">"net"</span><span class="special">),</span>
 260         <span class="comment">// We also can separate statistic records in a different channel</span>
 261         <span class="comment">// in order to route them to a different sink</span>
 262         <span class="identifier">m_stat</span><span class="special">(</span><span class="identifier">keywords</span><span class="special">::</span><span class="identifier">channel</span> <span class="special">=</span> <span class="string">"stat"</span><span class="special">)</span>
 263     <span class="special">{</span>
 264     <span class="special">}</span>
 265
 266     <span class="keyword">void</span> <span class="identifier">on_connected</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">remote_addr</span><span class="special">)</span>
 267     <span class="special">{</span>
 268         <span class="comment">// Add the remote address to both channels</span>
 269         <span class="identifier">attrs</span><span class="special">::</span><span class="identifier">constant</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="identifier">addr</span><span class="special">(</span><span class="identifier">remote_addr</span><span class="special">);</span>
 270         <span class="identifier">m_net_remote_addr</span> <span class="special">=</span> <span class="identifier">m_net</span><span class="special">.</span><span class="identifier">add_attribute</span><span class="special">(</span><span class="string">"RemoteAddress"</span><span class="special">,</span> <span class="identifier">addr</span><span class="special">).</span><span class="identifier">first</span><span class="special">;</span>
 271         <span class="identifier">m_stat_remote_addr</span> <span class="special">=</span> <span class="identifier">m_stat</span><span class="special">.</span><span class="identifier">add_attribute</span><span class="special">(</span><span class="string">"RemoteAddress"</span><span class="special">,</span> <span class="identifier">addr</span><span class="special">).</span><span class="identifier">first</span><span class="special">;</span>
 272
 273         <span class="comment">// Put message to the "net" channel</span>
 274         <span class="identifier">BOOST_LOG</span><span class="special">(</span><span class="identifier">m_net</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="string">"Connection established"</span><span class="special">;</span>
 275     <span class="special">}</span>
 276
 277     <span class="keyword">void</span> <span class="identifier">on_disconnected</span><span class="special">()</span>
 278     <span class="special">{</span>
 279         <span class="comment">// Put message to the "net" channel</span>
 280         <span class="identifier">BOOST_LOG</span><span class="special">(</span><span class="identifier">m_net</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="string">"Connection shut down"</span><span class="special">;</span>
 281
 282         <span class="comment">// Remove the attribute with the remote address</span>
 283         <span class="identifier">m_net</span><span class="special">.</span><span class="identifier">remove_attribute</span><span class="special">(</span><span class="identifier">m_net_remote_addr</span><span class="special">);</span>
 284         <span class="identifier">m_stat</span><span class="special">.</span><span class="identifier">remove_attribute</span><span class="special">(</span><span class="identifier">m_stat_remote_addr</span><span class="special">);</span>
 285     <span class="special">}</span>
 286
 287     <span class="keyword">void</span> <span class="identifier">on_data_received</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">size</span><span class="special">)</span>
 288     <span class="special">{</span>
 289         <span class="identifier">BOOST_LOG</span><span class="special">(</span><span class="identifier">m_stat</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">"ReceivedSize"</span><span class="special">,</span> <span class="identifier">size</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="string">"Some data received"</span><span class="special">;</span>
 290     <span class="special">}</span>
 291
 292     <span class="keyword">void</span> <span class="identifier">on_data_sent</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">size</span><span class="special">)</span>
 293     <span class="special">{</span>
 294         <span class="identifier">BOOST_LOG</span><span class="special">(</span><span class="identifier">m_stat</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">"SentSize"</span><span class="special">,</span> <span class="identifier">size</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="string">"Some data sent"</span><span class="special">;</span>
 295     <span class="special">}</span>
 296 <span class="special">};</span>
 297 </pre>
 298 <p>
 299         </p>
 300 <p>
 301           It is also possible to set the channel name of individual log records.
 302           This can be useful when a <a class="link" href="sources.html#log.detailed.sources.global_storage" title="Global storage for loggers">global
 303           logger</a> is used instead of an object-specific one. The channel name
 304           can be set by calling the <code class="computeroutput"><span class="identifier">channel</span></code>
 305           modifier on the logger or by using a special macro for logging. For example:
 306         </p>
 307 <p>
 308 </p>
 309 <pre class="programlisting"><span class="comment">// Define a global logger</span>
 310 <span class="identifier">BOOST_LOG_INLINE_GLOBAL_LOGGER_CTOR_ARGS</span><span class="special">(</span><span class="identifier">my_logger</span><span class="special">,</span> <span class="identifier">src</span><span class="special">::</span><span class="identifier">channel_logger_mt</span><span class="special">&lt;</span> <span class="special">&gt;,</span> <span class="special">(</span><span class="identifier">keywords</span><span class="special">::</span><span class="identifier">channel</span> <span class="special">=</span> <span class="string">"general"</span><span class="special">))</span>
 311
 312 <span class="keyword">class</span> <span class="identifier">network_connection</span>
 313 <span class="special">{</span>
 314     <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">m_remote_addr</span><span class="special">;</span>
 315
 316 <span class="keyword">public</span><span class="special">:</span>
 317     <span class="keyword">void</span> <span class="identifier">on_connected</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">remote_addr</span><span class="special">)</span>
 318     <span class="special">{</span>
 319         <span class="identifier">m_remote_addr</span> <span class="special">=</span> <span class="identifier">remote_addr</span><span class="special">;</span>
 320
 321         <span class="comment">// Put message to the "net" channel</span>
 322         <span class="identifier">BOOST_LOG_CHANNEL</span><span class="special">(</span><span class="identifier">my_logger</span><span class="special">::</span><span class="identifier">get</span><span class="special">(),</span> <span class="string">"net"</span><span class="special">)</span>
 323             <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">"RemoteAddress"</span><span class="special">,</span> <span class="identifier">m_remote_addr</span><span class="special">)</span>
 324             <span class="special">&lt;&lt;</span> <span class="string">"Connection established"</span><span class="special">;</span>
 325     <span class="special">}</span>
 326
 327     <span class="keyword">void</span> <span class="identifier">on_disconnected</span><span class="special">()</span>
 328     <span class="special">{</span>
 329         <span class="comment">// Put message to the "net" channel</span>
 330         <span class="identifier">BOOST_LOG_CHANNEL</span><span class="special">(</span><span class="identifier">my_logger</span><span class="special">::</span><span class="identifier">get</span><span class="special">(),</span> <span class="string">"net"</span><span class="special">)</span>
 331             <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">"RemoteAddress"</span><span class="special">,</span> <span class="identifier">m_remote_addr</span><span class="special">)</span>
 332             <span class="special">&lt;&lt;</span> <span class="string">"Connection shut down"</span><span class="special">;</span>
 333
 334         <span class="identifier">m_remote_addr</span><span class="special">.</span><span class="identifier">clear</span><span class="special">();</span>
 335     <span class="special">}</span>
 336
 337     <span class="keyword">void</span> <span class="identifier">on_data_received</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">size</span><span class="special">)</span>
 338     <span class="special">{</span>
 339         <span class="identifier">BOOST_LOG_CHANNEL</span><span class="special">(</span><span class="identifier">my_logger</span><span class="special">::</span><span class="identifier">get</span><span class="special">(),</span> <span class="string">"stat"</span><span class="special">)</span>
 340             <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">"RemoteAddress"</span><span class="special">,</span> <span class="identifier">m_remote_addr</span><span class="special">)</span>
 341             <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">"ReceivedSize"</span><span class="special">,</span> <span class="identifier">size</span><span class="special">)</span>
 342             <span class="special">&lt;&lt;</span> <span class="string">"Some data received"</span><span class="special">;</span>
 343     <span class="special">}</span>
 344
 345     <span class="keyword">void</span> <span class="identifier">on_data_sent</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">size</span><span class="special">)</span>
 346     <span class="special">{</span>
 347         <span class="identifier">BOOST_LOG_CHANNEL</span><span class="special">(</span><span class="identifier">my_logger</span><span class="special">::</span><span class="identifier">get</span><span class="special">(),</span> <span class="string">"stat"</span><span class="special">)</span>
 348             <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">"RemoteAddress"</span><span class="special">,</span> <span class="identifier">m_remote_addr</span><span class="special">)</span>
 349             <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">"SentSize"</span><span class="special">,</span> <span class="identifier">size</span><span class="special">)</span>
 350             <span class="special">&lt;&lt;</span> <span class="string">"Some data sent"</span><span class="special">;</span>
 351     <span class="special">}</span>
 352 <span class="special">};</span>
 353 </pre>
 354 <p>
 355         </p>
 356 <p>
 357           Note that changing the channel name is persistent, so unless the channel
 358           name is reset, the subsequent records will also belong to the new channel.
 359         </p>
 360 <div class="tip"><table border="0" summary="Tip">
 361 <tr>
 362 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../../../doc/src/images/tip.png"></td>
 363 <th align="left">Tip</th>
 364 </tr>
 365 <tr><td align="left" valign="top"><p>
 366             For performance reasons it is advised to avoid dynamically setting the
 367             channel name individually for every log record, when possible. Changing
 368             the channel name involves dynamic memory allocation. Using distinct loggers
 369             for different channels allows to avoid this overhead.
 370           </p></td></tr>
 371 </table></div>
 372 </div>
 373 <div class="section">
 374 <div class="titlepage"><div><div><h4 class="title">
 375 <a name="log.detailed.sources.exception_handling"></a><a class="link" href="sources.html#log.detailed.sources.exception_handling" title="Loggers with exception handling support">Loggers with
 376         exception handling support</a>
 377 </h4></div></div></div>
 378 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><code class="computeroutput"><a class="link" href="../../logging_sources.html#header.boost.log.sources.exception_handler_feature_hpp" title="Header &lt;boost/log/sources/exception_handler_feature.hpp&gt;">boost/log/sources/exception_handler_feature.hpp</a></code><span class="special">&gt;</span>
 379 </pre>
 380 <p>
 381           The library provides a logger feature that enables the user to handle and/or
 382           suppress exceptions at the logger level. The <code class="computeroutput"><a class="link" href="../../boost/log/sources/exception_handler.html" title="Struct exception_handler">exception_handler</a></code>
 383           feature adds a <code class="computeroutput"><span class="identifier">set_exception_handler</span></code>
 384           method to the logger that allows setting a function object to be called
 385           if an exception is thrown from the logging core during the filtering or
 386           processing of log records. One can use the <a class="link" href="utilities.html#log.detailed.utilities.exception_handlers" title="Exception handlers">library-provided
 387           adapters</a> to simplify implementing exception handlers. Usage example
 388           is as follows:
 389         </p>
 390 <p>
 391 </p>
 392 <pre class="programlisting"><span class="keyword">enum</span> <span class="identifier">severity_level</span>
 393 <span class="special">{</span>
 394     <span class="identifier">normal</span><span class="special">,</span>
 395     <span class="identifier">warning</span><span class="special">,</span>
 396     <span class="identifier">error</span>
 397 <span class="special">};</span>
 398
 399 <span class="comment">// A logger class that allows to intercept exceptions and supports severity level</span>
 400 <span class="keyword">class</span> <span class="identifier">my_logger_mt</span> <span class="special">:</span>
 401     <span class="keyword">public</span> <span class="identifier">src</span><span class="special">::</span><span class="identifier">basic_composite_logger</span><span class="special">&lt;</span>
 402         <span class="keyword">char</span><span class="special">,</span>
 403         <span class="identifier">my_logger_mt</span><span class="special">,</span>
 404         <span class="identifier">src</span><span class="special">::</span><span class="identifier">multi_thread_model</span><span class="special">&lt;</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">shared_mutex</span> <span class="special">&gt;,</span>
 405         <span class="identifier">src</span><span class="special">::</span><span class="identifier">features</span><span class="special">&lt;</span>
 406             <span class="identifier">src</span><span class="special">::</span><span class="identifier">severity</span><span class="special">&lt;</span> <span class="identifier">severity_level</span> <span class="special">&gt;,</span>
 407             <span class="identifier">src</span><span class="special">::</span><span class="identifier">exception_handler</span>
 408         <span class="special">&gt;</span>
 409     <span class="special">&gt;</span>
 410 <span class="special">{</span>
 411     <span class="identifier">BOOST_LOG_FORWARD_LOGGER_MEMBERS</span><span class="special">(</span><span class="identifier">my_logger_mt</span><span class="special">)</span>
 412 <span class="special">};</span>
 413
 414 <span class="identifier">BOOST_LOG_INLINE_GLOBAL_LOGGER_INIT</span><span class="special">(</span><span class="identifier">my_logger</span><span class="special">,</span> <span class="identifier">my_logger_mt</span><span class="special">)</span>
 415 <span class="special">{</span>
 416     <span class="identifier">my_logger_mt</span> <span class="identifier">lg</span><span class="special">;</span>
 417
 418     <span class="comment">// Set up exception handler: all exceptions that occur while</span>
 419     <span class="comment">// logging through this logger, will be suppressed</span>
 420     <span class="identifier">lg</span><span class="special">.</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>
 421
 422     <span class="keyword">return</span> <span class="identifier">lg</span><span class="special">;</span>
 423 <span class="special">}</span>
 424
 425 <span class="keyword">void</span> <span class="identifier">logging_function</span><span class="special">()</span>
 426 <span class="special">{</span>
 427     <span class="comment">// This will not throw</span>
 428     <span class="identifier">BOOST_LOG_SEV</span><span class="special">(</span><span class="identifier">my_logger</span><span class="special">::</span><span class="identifier">get</span><span class="special">(),</span> <span class="identifier">normal</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="string">"Hello, world"</span><span class="special">;</span>
 429 <span class="special">}</span>
 430 </pre>
 431 <p>
 432         </p>
 433 <div class="tip"><table border="0" summary="Tip">
 434 <tr>
 435 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../../../doc/src/images/tip.png"></td>
 436 <th align="left">Tip</th>
 437 </tr>
 438 <tr><td align="left" valign="top"><p>
 439             <a class="link" href="../detailed.html#log.detailed.core.core.exception_handling" title="Exception handling">Logging core</a>
 440             and <a class="link" href="sink_frontends.html#log.detailed.sink_frontends.basic_services.exception_handling" title="Exception handling">sink
 441             frontends</a> also support installing exception handlers.
 442           </p></td></tr>
 443 </table></div>
 444 </div>
 445 <div class="section">
 446 <div class="titlepage"><div><div><h4 class="title">
 447 <a name="log.detailed.sources.mixed_loggers"></a><a class="link" href="sources.html#log.detailed.sources.mixed_loggers" title="Loggers with mixed features">Loggers with mixed
 448         features</a>
 449 </h4></div></div></div>
 450 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><code class="computeroutput"><a class="link" href="../../logging_sources.html#header.boost.log.sources.severity_channel_logger_hpp" title="Header &lt;boost/log/sources/severity_channel_logger.hpp&gt;">boost/log/sources/severity_channel_logger.hpp</a></code><span class="special">&gt;</span>
 451 </pre>
 452 <p>
 453           If you wonder whether you can use a mixed set of several logger features
 454           in one logger, then yes, you certainly can. The library provides <code class="computeroutput"><a class="link" href="../../boost/log/sources/severity_channel_logger.html" title="Class template severity_channel_logger">severity_channel_logger</a></code>
 455           and <code class="computeroutput"><a class="link" href="../../boost/log/sources/severity_channel_logger_mt.html" title="Class template severity_channel_logger_mt">severity_channel_logger_mt</a></code>
 456           (with their wide-char analogues <code class="computeroutput"><a class="link" href="../../boost/log/sources/wseverity_channel_logger.html" title="Class template wseverity_channel_logger">wseverity_channel_logger</a></code>
 457           and <code class="computeroutput"><a class="link" href="../../boost/log/sources/wseverit_idm45711346915184.html" title="Class template wseverity_channel_logger_mt">wseverity_channel_logger_mt</a></code>)
 458           which combine features of the described loggers with <a class="link" href="sources.html#log.detailed.sources.severity_level_logger" title="Loggers with severity level support">severity
 459           level</a> and <a class="link" href="sources.html#log.detailed.sources.channel_logger" title="Loggers with channel support">channels</a>
 460           support. The composite loggers are templates, too, which allows you to
 461           specify severity level and channel types. You can also design your own
 462           logger features and combine them with the ones provided by the library,
 463           as described in the <a class="link" href="../extension/sources.html" title="Writing your own sources">Extending the
 464           library</a> section.
 465         </p>
 466 <p>
 467           The usage of the loggers with several features does not conceptually differ
 468           from the usage of the single-featured loggers. For instance, here is how
 469           a <code class="computeroutput"><a class="link" href="../../boost/log/sources/severity_channel_logger_mt.html" title="Class template severity_channel_logger_mt">severity_channel_logger_mt</a></code>
 470           could be used:
 471         </p>
 472 <p>
 473 </p>
 474 <pre class="programlisting"><span class="keyword">enum</span> <span class="identifier">severity_level</span>
 475 <span class="special">{</span>
 476     <span class="identifier">normal</span><span class="special">,</span>
 477     <span class="identifier">notification</span><span class="special">,</span>
 478     <span class="identifier">warning</span><span class="special">,</span>
 479     <span class="identifier">error</span><span class="special">,</span>
 480     <span class="identifier">critical</span>
 481 <span class="special">};</span>
 482
 483 <span class="keyword">typedef</span> <span class="identifier">src</span><span class="special">::</span><span class="identifier">severity_channel_logger_mt</span><span class="special">&lt;</span>
 484     <span class="identifier">severity_level</span><span class="special">,</span>     <span class="comment">// the type of the severity level</span>
 485     <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span>         <span class="comment">// the type of the channel name</span>
 486 <span class="special">&gt;</span> <span class="identifier">my_logger_mt</span><span class="special">;</span>
 487
 488
 489 <span class="identifier">BOOST_LOG_INLINE_GLOBAL_LOGGER_INIT</span><span class="special">(</span><span class="identifier">my_logger</span><span class="special">,</span> <span class="identifier">my_logger_mt</span><span class="special">)</span>
 490 <span class="special">{</span>
 491     <span class="comment">// Specify the channel name on construction, similarly as with the channel_logger</span>
 492     <span class="keyword">return</span> <span class="identifier">my_logger_mt</span><span class="special">(</span><span class="identifier">keywords</span><span class="special">::</span><span class="identifier">channel</span> <span class="special">=</span> <span class="string">"my_logger"</span><span class="special">);</span>
 493 <span class="special">}</span>
 494
 495 <span class="keyword">void</span> <span class="identifier">logging_function</span><span class="special">()</span>
 496 <span class="special">{</span>
 497     <span class="comment">// Do logging with the severity level. The record will have both</span>
 498     <span class="comment">// the severity level and the channel name attached.</span>
 499     <span class="identifier">BOOST_LOG_SEV</span><span class="special">(</span><span class="identifier">my_logger</span><span class="special">::</span><span class="identifier">get</span><span class="special">(),</span> <span class="identifier">normal</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="string">"Hello, world!"</span><span class="special">;</span>
 500 <span class="special">}</span>
 501 </pre>
 502 <p>
 503         </p>
 504 </div>
 505 <div class="section">
 506 <div class="titlepage"><div><div><h4 class="title">
 507 <a name="log.detailed.sources.global_storage"></a><a class="link" href="sources.html#log.detailed.sources.global_storage" title="Global storage for loggers">Global storage
 508         for loggers</a>
 509 </h4></div></div></div>
 510 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><code class="computeroutput"><a class="link" href="../../logging_sources.html#header.boost.log.sources.global_logger_storage_hpp" title="Header &lt;boost/log/sources/global_logger_storage.hpp&gt;">boost/log/sources/global_logger_storage.hpp</a></code><span class="special">&gt;</span>
 511 </pre>
 512 <p>
 513           Sometimes it is inconvenient to have a logger object to be able to write
 514           logs. This issue is often present in functional-style code with no obvious
 515           places where a logger could be stored. Another domain where the problem
 516           persists is generic libraries that would benefit from logging. In such
 517           cases it would be more convenient to have one or several global loggers
 518           in order to easily access them in every place when needed. In this regard
 519           <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span></code> is a good example of such a logger.
 520         </p>
 521 <p>
 522           The library provides a way to declare global loggers that can be accessed
 523           pretty much like <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span></code>. In fact, this feature can be used
 524           with any logger, including user-defined ones. Having declared a global
 525           logger, one can be sure to have a thread-safe access to this logger instance
 526           from any place of the application code. The library also guarantees that
 527           a global logger instance will be unique even across module boundaries.
 528           This allows employing logging even in header-only components that may get
 529           compiled into different modules.
 530         </p>
 531 <p>
 532           One may wonder why there is a need for something special in order to create
 533           global loggers. Why not just declare a logger variable at namespace scope
 534           and use it wherever you need? While technically this is possible, declaring
 535           and using global logger variables is complicated for the following reasons:
 536         </p>
 537 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 538 <li class="listitem">
 539               Order of initialization of namespace scope variables is not specified
 540               by the C++ Standard. This means that generally you cannot use the logger
 541               during this stage of initialization (i.e. before <code class="computeroutput"><span class="identifier">main</span></code>).
 542             </li>
 543 <li class="listitem">
 544               Initialization of namespace scope variables is not thread-safe. You
 545               may end up initializing the same logger twice or using an uninitialized
 546               logger.
 547             </li>
 548 <li class="listitem">
 549               Using namespace scope variables in a header-only library is quite complicated.
 550               One either has to declare a variable with external linkage and define
 551               it only in a single translation unit (that is, in a separate .cpp file,
 552               which defeats the "header-only" thesis), or define a variable
 553               with internal linkage, or as a special case in an anonymous namespace
 554               (this will most likely break ODR and give unexpected results when the
 555               header is used in different translation units). There are other compiler-specific
 556               and standard tricks to tackle the problem, but they are not quite trivial
 557               and portable.
 558             </li>
 559 <li class="listitem">
 560               On most platforms namespace scope variables are local to the module
 561               where they were compiled in. That is, if variable <code class="computeroutput"><span class="identifier">a</span></code>
 562               has external linkage and was compiled into modules X and Y, each of
 563               these modules has its own copy of variable <code class="computeroutput"><span class="identifier">a</span></code>.
 564               To make things worse, on other platforms this variable can be shared
 565               between the modules.
 566             </li>
 567 </ul></div>
 568 <p>
 569           Global logger storage is intended to eliminate all these problems.
 570         </p>
 571 <p>
 572           The easiest way to declare a global logger is to use the following macro:
 573         </p>
 574 <pre class="programlisting"><code class="computeroutput"><a class="link" href="../../BOOST_LO_idm45711347105328.html" title="Macro BOOST_LOG_INLINE_GLOBAL_LOGGER_DEFAULT">BOOST_LOG_INLINE_GLOBAL_LOGGER_DEFAULT</a></code><span class="special">(</span><span class="identifier">my_logger</span><span class="special">,</span> <span class="identifier">src</span><span class="special">::</span><span class="identifier">severity_logger_mt</span><span class="special">&lt;</span> <span class="special">&gt;)</span>
 575 </pre>
 576 <p>
 577           The <code class="computeroutput"><span class="identifier">my_logger</span></code> argument
 578           gives the logger a name that may be used to acquire the logger instance.
 579           This name acts as a tag of the declared logger. The second parameter denotes
 580           the logger type. In multithreaded applications, when the logger can be
 581           accessed from different threads, users will normally want to use the thread-safe
 582           versions of loggers.
 583         </p>
 584 <p>
 585           If passing arguments to the logger constructor is needed, there is another
 586           macro:
 587         </p>
 588 <pre class="programlisting"><code class="computeroutput"><a class="link" href="../../BOOST_LO_idm45711347103344.html" title="Macro BOOST_LOG_INLINE_GLOBAL_LOGGER_CTOR_ARGS">BOOST_LOG_INLINE_GLOBAL_LOGGER_CTOR_ARGS</a></code><span class="special">(</span>
 589     <span class="identifier">my_logger</span><span class="special">,</span>
 590     <span class="identifier">src</span><span class="special">::</span><span class="identifier">severity_channel_logger</span><span class="special">&lt;</span> <span class="special">&gt;,</span>
 591     <span class="special">(</span><span class="identifier">keywords</span><span class="special">::</span><span class="identifier">severity</span> <span class="special">=</span> <span class="identifier">error</span><span class="special">)(</span><span class="identifier">keywords</span><span class="special">::</span><span class="identifier">channel</span> <span class="special">=</span> <span class="string">"my_channel"</span><span class="special">))</span>
 592 </pre>
 593 <p>
 594           The last macro argument is a <a href="http://www.boost.org/doc/libs/release/libs/preprocessor/doc/index.html" target="_top">Boost.Preprocessor</a>
 595           sequence of arguments passed to the logger constructor. Be careful, however,
 596           when using non-constant expressions and references to objects as constructor
 597           arguments, since the arguments are evaluated only once and it is often
 598           difficult to tell the exact moment when it is done. The logger is constructed
 599           on the first request from whichever part of the application that has the
 600           knowledge of the logger declaration. It is up to user to make sure that
 601           all arguments have valid states at that point.
 602         </p>
 603 <p>
 604           The third macro of this section provides maximum initialization flexibility,
 605           allowing the user to actually define the logic of creating the logger.
 606         </p>
 607 <pre class="programlisting"><code class="computeroutput"><a class="link" href="../../BOOST_LO_idm45711347107312.html" title="Macro BOOST_LOG_INLINE_GLOBAL_LOGGER_INIT">BOOST_LOG_INLINE_GLOBAL_LOGGER_INIT</a></code><span class="special">(</span><span class="identifier">my_logger</span><span class="special">,</span> <span class="identifier">src</span><span class="special">::</span><span class="identifier">severity_logger_mt</span><span class="special">)</span>
 608 <span class="special">{</span>
 609     <span class="comment">// Do something that needs to be done on logger initialization,</span>
 610     <span class="comment">// e.g. add a stop watch attribute.</span>
 611     <span class="identifier">src</span><span class="special">::</span><span class="identifier">severity_logger_mt</span><span class="special">&lt;</span> <span class="special">&gt;</span> <span class="identifier">lg</span><span class="special">;</span>
 612     <span class="identifier">lg</span><span class="special">.</span><span class="identifier">add_attribute</span><span class="special">(</span><span class="string">"StopWatch"</span><span class="special">,</span> <span class="identifier">attrs</span><span class="special">::</span><span class="identifier">timer</span><span class="special">());</span>
 613     <span class="comment">// The initializing routine must return the logger instance</span>
 614     <span class="keyword">return</span> <span class="identifier">lg</span><span class="special">;</span>
 615 <span class="special">}</span>
 616 </pre>
 617 <p>
 618           Like the <code class="computeroutput"><a class="link" href="../../BOOST_LO_idm45711347103344.html" title="Macro BOOST_LOG_INLINE_GLOBAL_LOGGER_CTOR_ARGS">BOOST_LOG_INLINE_GLOBAL_LOGGER_CTOR_ARGS</a></code>
 619           macro, the initialization code is called only once, on the first request
 620           of the logger.
 621         </p>
 622 <div class="important"><table border="0" summary="Important">
 623 <tr>
 624 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../../../../doc/src/images/important.png"></td>
 625 <th align="left">Important</th>
 626 </tr>
 627 <tr><td align="left" valign="top"><p>
 628             Beware of One Definition Rule (ODR) issues. Regardless of the way of
 629             logger declaration you choose, you should ensure that <span class="underline">the
 630             logger is declared in exactly the same way at all occurrences</span>
 631             and <span class="underline">all symbol names involved in the declaration
 632             resolve to the same entities</span>. The latter includes the names
 633             used within the initialization routine of the <code class="computeroutput"><a class="link" href="../../BOOST_LO_idm45711347107312.html" title="Macro BOOST_LOG_INLINE_GLOBAL_LOGGER_INIT">BOOST_LOG_INLINE_GLOBAL_LOGGER_INIT</a></code>
 634             macro, such as references to external variables, functions and types.
 635             The library tries to protect itself from ODR violations to a certain
 636             degree, but in general the behavior is undefined if the rule is violated.
 637           </p></td></tr>
 638 </table></div>
 639 <p>
 640           In order to alleviate ODR problems, it is possible to separate the logger
 641           declaration and its initialization routine. The library provides the following
 642           macros to achieve this:
 643         </p>
 644 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 645 <li class="listitem">
 646               <code class="computeroutput"><a class="link" href="../../BOOST_LOG_GLOBAL_LOGGER.html" title="Macro BOOST_LOG_GLOBAL_LOGGER">BOOST_LOG_GLOBAL_LOGGER</a></code>
 647               provides the logger declaration. It can be used in a header, similarly
 648               to the <code class="computeroutput"><span class="identifier">BOOST_LOG_INLINE_GLOBAL_LOGGER</span><span class="special">*</span></code> macros described above.
 649             </li>
 650 <li class="listitem">
 651               <code class="computeroutput"><a class="link" href="../../BOOST_LO_idm45711347113728.html" title="Macro BOOST_LOG_GLOBAL_LOGGER_INIT">BOOST_LOG_GLOBAL_LOGGER_INIT</a></code>,
 652               <code class="computeroutput"><a class="link" href="../../BOOST_LO_idm45711347111744.html" title="Macro BOOST_LOG_GLOBAL_LOGGER_DEFAULT">BOOST_LOG_GLOBAL_LOGGER_DEFAULT</a></code>
 653               and <code class="computeroutput"><a class="link" href="../../BOOST_LO_idm45711347109744.html" title="Macro BOOST_LOG_GLOBAL_LOGGER_CTOR_ARGS">BOOST_LOG_GLOBAL_LOGGER_CTOR_ARGS</a></code>
 654               define the logger initialization routine. Their semantics and usage
 655               is similar to the corresponding <code class="computeroutput"><span class="identifier">BOOST_LOG_INLINE_GLOBAL_LOGGER</span><span class="special">*</span></code> macros, for one exception: these macros
 656               should be used in a single .cpp file.
 657             </li>
 658 </ul></div>
 659 <p>
 660           For example:
 661         </p>
 662 <pre class="programlisting"><span class="comment">// my_logger.h</span>
 663 <span class="comment">// ===========</span>
 664
 665 <span class="identifier">BOOST_LOG_GLOBAL_LOGGER</span><span class="special">(</span><span class="identifier">my_logger</span><span class="special">,</span> <span class="identifier">src</span><span class="special">::</span><span class="identifier">severity_logger_mt</span><span class="special">)</span>
 666
 667
 668 <span class="comment">// my_logger.cpp</span>
 669 <span class="comment">// =============</span>
 670
 671 <span class="preprocessor">#include</span> <span class="string">"my_logger.h"</span>
 672
 673 <span class="identifier">BOOST_LOG_GLOBAL_LOGGER_INIT</span><span class="special">(</span><span class="identifier">my_logger</span><span class="special">,</span> <span class="identifier">src</span><span class="special">::</span><span class="identifier">severity_logger_mt</span><span class="special">)</span>
 674 <span class="special">{</span>
 675     <span class="identifier">src</span><span class="special">::</span><span class="identifier">severity_logger_mt</span><span class="special">&lt;</span> <span class="special">&gt;</span> <span class="identifier">lg</span><span class="special">;</span>
 676     <span class="identifier">lg</span><span class="special">.</span><span class="identifier">add_attribute</span><span class="special">(</span><span class="string">"StopWatch"</span><span class="special">,</span> <span class="identifier">attrs</span><span class="special">::</span><span class="identifier">timer</span><span class="special">());</span>
 677     <span class="keyword">return</span> <span class="identifier">lg</span><span class="special">;</span>
 678 <span class="special">}</span>
 679 </pre>
 680 <p>
 681           Regardless of the macro you used to declare the logger, you can acquire
 682           the logger instance with the static <code class="computeroutput"><span class="identifier">get</span></code>
 683           function of the logger tag:
 684         </p>
 685 <pre class="programlisting"><span class="identifier">src</span><span class="special">::</span><span class="identifier">severity_logger_mt</span><span class="special">&lt;</span> <span class="special">&gt;&amp;</span> <span class="identifier">lg</span> <span class="special">=</span> <span class="identifier">my_logger</span><span class="special">::</span><span class="identifier">get</span><span class="special">();</span>
 686 </pre>
 687 <p>
 688           Further usage of the logger is the same as if it was a regular logger object
 689           of the corresponding type.
 690         </p>
 691 <div class="warning"><table border="0" summary="Warning">
 692 <tr>
 693 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../../../doc/src/images/warning.png"></td>
 694 <th align="left">Warning</th>
 695 </tr>
 696 <tr><td align="left" valign="top"><p>
 697             It should be noted that it is not advised to use global loggers during
 698             the deinitialization stage of the application. Like any other global
 699             object in your application, the global logger may get destroyed before
 700             you try to use it. In such cases it's better to have a dedicated logger
 701             object that is guaranteed to be available as long as needed.
 702           </p></td></tr>
 703 </table></div>
 704 </div>
 705 </div>
 706 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 707 <td align="left"></td>
 708 <td align="right"><div class="copyright-footer">Copyright &#169; 2007-2016 Andrey Semashev<p>
 709         Distributed under the Boost Software License, Version 1.0. (See accompanying
 710         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>).
 711       </p>
 712 </div></td>
 713 </tr></table>
 714 <hr>
 715 <div class="spirit-nav">
 716 <a accesskey="p" href="../detailed.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="sink_frontends.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
 717 </div>
 718 </body>
 719 </html>