<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html><head><meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1"> <title>rlog: RLog Channels</title> <link href="doxygen.css" rel="stylesheet" type="text/css"> </head><body> <!-- Generated by Doxygen 1.4.3 --> <div class="qindex"><a class="qindex" href="index.html">Main Page</a> | <a class="qindex" href="modules.html">Modules</a> | <a class="qindex" href="annotated.html">Class List</a> | <a class="qindex" href="dirs.html">Directories</a> | <a class="qindex" href="files.html">File List</a> | <a class="qindex" href="functions.html">Class Members</a> | <a class="qindex" href="pages.html">Related Pages</a></div> <h1><a class="anchor" name="channel">RLog Channels</a></h1>An RLog Channel is a naming method for logging messages.<p> All logs are associated with a single channel, however there a variety of ways of subscribing to a log message.<h2><a class="anchor" name="hierarchy"> Channel Hierarchy</a></h2> Channels are hierarchical. For example, if a log message is published on the "debug" channel: <div class="fragment"><pre class="fragment"> <a class="code" href="group__RLogMacros.html#ga0">rDebug</a>(<span class="stringliteral">"hi"</span>); <span class="comment">// same as</span> <span class="keyword">static</span> RLogChannel *myChannel = DEF_CHANNEL(<span class="stringliteral">"debug"</span>, Log_Debug); <a class="code" href="group__RLogMacros.html#ga4">rLog</a>(myChannel, <span class="stringliteral">"hi"</span>); </pre></div><p> In the example above, all subscribers to the "debug" channel receive the messages, but <em>not</em> subscribers to "debug/foo" or other sub-channels.<p> If a log is published under "debug/foo/bar": <div class="fragment"><pre class="fragment"> <span class="keyword">static</span> RLogChannel *myChannel = DEF_CHANNEL(<span class="stringliteral">"debug/foo/bar"</span>, Log_Debug); <a class="code" href="group__RLogMacros.html#ga4">rLog</a>(myChannel, <span class="stringliteral">"hi"</span>); </pre></div><p> In that example, all subscribers to "debug/foo/bar", "debug/foo", and "debug" will receive the message.<p> All channels are considered to be derived from a root channel. It doesn't have a true name and is referenced as the empty string "". So, to capture <em>all</em> messages: <div class="fragment"><pre class="fragment"> <span class="comment">// capture all messages and log them to stderr</span> StdioNode stdLog( STDERR_FILENO ); stdLog.subscribeTo( GetGlobalChannel(<span class="stringliteral">""</span>) ); <span class="comment">// empty string is root channel</span> </pre></div><h2><a class="anchor" name="channelcomponents"> Channel Components</a></h2> Or in mathematical terms, the cross product of channels and components.<p> Channels are componentized. By default, all log messages using one of the rLog type macros is actually published on the component-specific version of the channel (the component being the value of RLOG_COMPONENT at compile time). So, instead of just saying a message was published on "debug" channel, we need to also say which component it was part of, which we could represent as a pair ( < COMPONENT, CHANNEL > ) -- eg <"rlog", "debug">.<p> This means that two separate components, both using <a class="el" href="group__RLogMacros.html#ga0">rDebug()</a> (for example) could be subscribed to separately, or together.<p> There is a way to subscribe to channels in the following ways:<ul> <li><COMPONENT, CHANNEL> : subscribe to a particular channel from a component</li><li><COMPONENT, *> : subscribe to all channels from a component</li><li><*, CHANNEL> : subscribe to a channel from <em>all</em> components</li><li><*, *> : subscribe to all channels from all components</li></ul> <p> <div class="fragment"><pre class="fragment">{ <span class="comment">// this is published on the channel "debug", and the component</span> <span class="comment">// [RLOG_COMPONENT]</span> <a class="code" href="group__RLogMacros.html#ga0">rDebug</a>(<span class="stringliteral">"hi"</span>); StdioNode stdLog( STDERR_FILENO ); <span class="comment">// subscribe to a particular channel, from the current component</span> <span class="comment">// ([RLOG_COMPONENT])</span> stdLog.subscribeTo( RLOG_CHANNEL(<span class="stringliteral">"debug/foo"</span>) ); <span class="comment">// subscribe to all channels from the current component ([RLOG_COMPONENT])</span> <span class="comment">// (the root channel is the empty string "")</span> stdLog.subscribeTo( RLOG_CHANNEL(<span class="stringliteral">""</span>) ); <span class="comment">// subscribe to a particular channel from all components</span> stdLog.subscribeTo( GetGlobalChannel(<span class="stringliteral">"debug/foo"</span>) ); <span class="comment">// subscribe to all channels from all components</span> stdLog.subscribeTo( GetGlobalChannel(<span class="stringliteral">""</span>) ); } </pre></div><p> As you can see from the pattern above, using the RLOG_CHANNEL() macro limits the selection to the current component. If you want to specify a component other then the current component, use GetComponentChannel() which takes the component name as the first argument.<p> An RLog Channel is a naming method for logging messages.<p> All logs are associated with a single channel, however there a variety of ways of subscribing to a log message.<h2><a class="anchor" name="hierarchy"> Channel Hierarchy</a></h2> Channels are hierarchical. For example, if a log message is published on the "debug" channel: <div class="fragment"><pre class="fragment"> <a class="code" href="group__RLogMacros.html#ga0">rDebug</a>(<span class="stringliteral">"hi"</span>); <span class="comment">// same as</span> <span class="keyword">static</span> RLogChannel *myChannel = DEF_CHANNEL(<span class="stringliteral">"debug"</span>, Log_Debug); <a class="code" href="group__RLogMacros.html#ga4">rLog</a>(myChannel, <span class="stringliteral">"hi"</span>); </pre></div><p> In the example above, all subscribers to the "debug" channel receive the messages, but <em>not</em> subscribers to "debug/foo" or other sub-channels.<p> If a log is published under "debug/foo/bar": <div class="fragment"><pre class="fragment"> <span class="keyword">static</span> RLogChannel *myChannel = DEF_CHANNEL(<span class="stringliteral">"debug/foo/bar"</span>, Log_Debug); <a class="code" href="group__RLogMacros.html#ga4">rLog</a>(myChannel, <span class="stringliteral">"hi"</span>); </pre></div><p> In that example, all subscribers to "debug/foo/bar", "debug/foo", and "debug" will receive the message.<p> All channels are considered to be derived from a root channel. It doesn't have a true name and is referenced as the empty string "". So, to capture <em>all</em> messages: <div class="fragment"><pre class="fragment"> <span class="comment">// capture all messages and log them to stderr</span> StdioNode stdLog( STDERR_FILENO ); stdLog.subscribeTo( GetGlobalChannel(<span class="stringliteral">""</span>) ); <span class="comment">// empty string is root channel</span> </pre></div><h2><a class="anchor" name="channelcomponents"> Channel Components</a></h2> Or in mathematical terms, the cross product of channels and components.<p> Channels are componentized. By default, all log messages using one of the rLog type macros is actually published on the component-specific version of the channel (the component being the value of RLOG_COMPONENT at compile time). So, instead of just saying a message was published on "debug" channel, we need to also say which component it was part of, which we could represent as a pair ( < COMPONENT, CHANNEL > ) -- eg <"rlog", "debug">.<p> This means that two separate components, both using <a class="el" href="group__RLogMacros.html#ga0">rDebug()</a> (for example) could be subscribed to separately, or together.<p> There is a way to subscribe to channels in the following ways:<ul> <li><COMPONENT, CHANNEL> : subscribe to a particular channel from a component</li><li><COMPONENT, *> : subscribe to all channels from a component</li><li><*, CHANNEL> : subscribe to a channel from <em>all</em> components</li><li><*, *> : subscribe to all channels from all components</li></ul> <p> <div class="fragment"><pre class="fragment">{ <span class="comment">// this is published on the channel "debug", and the component</span> <span class="comment">// [RLOG_COMPONENT]</span> <a class="code" href="group__RLogMacros.html#ga0">rDebug</a>(<span class="stringliteral">"hi"</span>); StdioNode stdLog( STDERR_FILENO ); <span class="comment">// subscribe to a particular channel, from the current component</span> <span class="comment">// ([RLOG_COMPONENT])</span> stdLog.subscribeTo( RLOG_CHANNEL(<span class="stringliteral">"debug/foo"</span>) ); <span class="comment">// subscribe to all channels from the current component ([RLOG_COMPONENT])</span> <span class="comment">// (the root channel is the empty string "")</span> stdLog.subscribeTo( RLOG_CHANNEL(<span class="stringliteral">""</span>) ); <span class="comment">// subscribe to a particular channel from all components</span> stdLog.subscribeTo( GetGlobalChannel(<span class="stringliteral">"debug/foo"</span>) ); <span class="comment">// subscribe to all channels from all components</span> stdLog.subscribeTo( GetGlobalChannel(<span class="stringliteral">""</span>) ); } </pre></div><p> As you can see from the pattern above, using the RLOG_CHANNEL() macro limits the selection to the current component. If you want to specify a component other then the current component, use GetComponentChannel() which takes the component name as the first argument. <hr size="1"><address style="align: right;"><small>Generated on Wed Oct 5 11:13:40 2005 for rlog by <a href="http://www.doxygen.org/index.html"> <img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.4.3 </small></address> </body> </html>