File: index.html

package info (click to toggle)
rlog 1.4-4.1
  • links: PTS
  • area: main
  • in suites: bookworm, sid
  • size: 2,660 kB
  • sloc: sh: 9,196; cpp: 1,601; makefile: 84
file content (109 lines) | stat: -rw-r--r-- 8,617 bytes parent folder | download | duplicates (6)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
<!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 - a C++ logging library</title>
<link href="doxygen.css" rel="stylesheet" type="text/css">
<link href="tabs.css" rel="stylesheet" type="text/css">
</head><body>
<!-- Generated by Doxygen 1.5.0 -->
<div class="tabs">
  <ul>
    <li id="current"><a href="index.html"><span>Main&nbsp;Page</span></a></li>
    <li><a href="modules.html"><span>Modules</span></a></li>
    <li><a href="annotated.html"><span>Classes</span></a></li>
    <li><a href="files.html"><span>Files</span></a></li>
    <li><a href="pages.html"><span>Related&nbsp;Pages</span></a></li>
  </ul></div>
<h1>RLog - a C++ logging library</h1>
<p>
<h3 align="center">1.3 </h3><h3>Copyright &copy; 2002-2004 Valient Gough &lt; vgough @ pobox . com &gt;</h3>
<p>
Distributed under the LGPL license, see COPYING for details.<h2><a class="anchor" name="introduction">
Introduction</a></h2>
RLog provides a flexible message logging facility for C++ programs and libraries. It is meant to be fast enough to leave in production code.<p>
RLog provides macros which are similar to Qt's debug macros, which are similar to simple printf() statements: <div class="fragment"><pre class="fragment"><span class="keywordtype">void</span> func(<span class="keywordtype">int</span> foo)
{
    <a class="code" href="group__RLogMacros.html#ge8be8a2d2e9da76cb70e2f29e0801f73">rDebug</a>(<span class="stringliteral">"foo = %i"</span>, foo);
    <span class="keywordtype">int</span> ans = 6 * 9;
    <span class="keywordflow">if</span>(ans != 42)
        <a class="code" href="group__RLogMacros.html#gd62ee67e7f1de16d4f71b1d8699cfac8">rWarning</a>(<span class="stringliteral">"ans = %i, expecting 42"</span>, ans);
    <a class="code" href="group__RLogMacros.html#gc31d5e1de248b22df42a34e58a2b7349">rError</a>(<span class="stringliteral">"I'm sorry %s, I can't do that (error code %i)"</span>, name, errno);
}
</pre></div><p>
The difference to Qt's macros is that the log messages are considered <em>publishers</em> and there can be any number of <em>subscribers</em> to log messages. Subscribers may choose which messages they want to receive in a number of different ways:<ul>
<li>subscribe to messages to a particular <em>channel</em>. Channels are hierarchical can be easily created. See <a class="el" href="channel.html">RLog Channels</a>.</li><li>subscribe to anything from a particular <em>component</em>. See <a class="el" href="component.html">RLog Components</a>.</li><li>subscribe to messages from a particular file name within a component.</li></ul>
<p>
If there are no subscribers to a particular logging statement, that statement can be said to be <em>dormant</em>. RLog is optimized to minimize overhead of dormant logging statements, with the goal of allowing logging to be left in release versions of software. This way if problems show up in production code, it is possible to activate logging statements in real time to aid debugging.<p>
As an indication of just how cheap a dormant logging statement is, on a Pentium-4 class CPU with g++ 3.3.1, a dormant log in a tight loop adds on the order of 2-6 (two to six) clock cycles of overhead (1). By comparison a simple logging function such as Qt's qDebug() adds about 1000 (a thousand) clock cycles of overhead - even when messages are being thrown away.<p>
In addition, logging statements in RLog can be individually activated at run-time without affecting any other statements, allowing targeted log reporting.<p>
<em>(1) The first time a logging statement is encountered, it must be registered in order to determine if there are any subscribers. So there is additional overhead the first time a statement is encountered. </em><h2><a class="anchor" name="use">
Using RLog</a></h2>
In order to begin using RLog in your code, you should do the following:<ul>
<li>define RLOG_COMPONENT in your build environment. Eg: librlog is built with -DRLOG_COMPONENT="rlog". You should use a unique name for your program or library (do not use "rlog"). If your program is made up of separate components, then you can define RLOG_COMPONENT as a different name for each component.</li><li>(optional) add a call to RLogInit() in your main program startup code. This is not a requirement, however not including it may reduce functionality of external rlog modules.</li><li>link with librlog</li><li>add subscribers (<a class="el" href="classrlog_1_1StdioNode.html">rlog::StdioNode</a> , <a class="el" href="classrlog_1_1SyslogNode.html">rlog::SyslogNode</a> , or your own) to catch any messages you are interested in.</li></ul>
<h2><a class="anchor" name="requirements">
Requirements</a></h2>
RLog has been tested on the following systems (all releases may not have been tested on all systems):<p>
<table style="width: 100%; text-align: left;" border="1" cellpadding="2" cellspacing="2">
<tr>
<th style="width: 104px; text-align: center;"><b>Platform</b><br>
  </th><th style="width: 149px; text-align: center;"><b>Operating System</b><br>
  </th><th style="width: 126px; text-align: center;"><b>Compiler</b><br>
  </th><th style="text-align: center;">Notes<br>
   </th></tr>
<tr>
<td style="background-color: rgb(153, 255, 153);">ix86<br>
  </td><td style="background-color: rgb(153, 255, 153);">SuSE 9.2<br>
  </td><td style="background-color: rgb(153, 255, 153);">GNU G++ 3.3.4<br>
  </td><td>binary RPM available<br>
   </td></tr>
<tr>
<td style="background-color: rgb(153, 255, 153);"><br>
  </td><td style="background-color: rgb(153, 255, 153);">SuSE 9.0<br>
  </td><td style="background-color: rgb(153, 255, 153);">Intel ICC 8.0<br>
  </td><td>last test was prior to RLog 1.3.4<br>
   </td></tr>
<tr>
<td style="background-color: rgb(153, 255, 153);"><br>
  </td><td style="background-color: rgb(153, 255, 153);">RedHat 7.3<br>
  </td><td style="background-color: rgb(153, 255, 153);">GNU G++ 2.96<br>
  </td><td>binary RPM available  </td></tr>
<tr>
<td style="background-color: rgb(153, 255, 153);"><br>
  </td><td style="background-color: rgb(153, 255, 153);">OpenBSD 3.4<br>
  </td><td style="background-color: rgb(153, 255, 153);">GNU G++ 2.95.3<br>
  </td><td>Tested with 1.3.5<br>
   </td></tr>
<tr>
<td style="background-color: rgb(153, 255, 153);"><br>
  </td><td style="background-color: rgb(153, 255, 153);">FreeBSD 4.10-beta<br>
  </td><td style="background-color: rgb(153, 255, 153);">GNU G++ 2.95.4<br>
  </td><td>Support added in 1.3.6 release<br>
   </td></tr>
<tr>
<td style="background-color: rgb(153, 255, 153);">sparc<br>
  </td><td style="background-color: rgb(153, 255, 153);">Solaris 5.9<br>
  </td><td style="background-color: rgb(153, 255, 153);">GNU G++ 3.3.2<br>
  </td><td><br>
   </td></tr>
<tr>
<td style="background-color: rgb(153, 255, 153);">PowerPC<br>
  </td><td style="background-color: rgb(153, 255, 153);">Darwin 5.5<br>
  </td><td style="background-color: rgb(153, 255, 153);">gcc-932.1<br>
  </td><td>Support added in 1.3.6 release<br>
   </td></tr>
</table>
<p>
To build development versions, you will also need the GNU autoconf tools (with automake and libtool). Documentation is built using Doxygen.<h2><a class="anchor" name="downloads">
Downloads</a></h2>
RLog is available in source code and RPM packaged binaries for some systems.<p>
RLog Version 1.3.7 - Oct 5, 2005 release.<ul>
<li>Tarball: <a href="http://arg0.net/users/vgough/download/rlog-1.3.7.tgz">rlog-1.3.7.tgz</a> + <a href="http://arg0.net/users/vgough/download/rlog-1.3.7.tgz.asc">tarball GPG signature</a></li><li>Source RPM: <a href="http://arg0.net/users/vgough/download/rlog-1.3.7-1.src.rpm">rlog-1.3.7-1.src.rpm</a></li></ul>
<p>
Binary packages:<ul>
<li>SuSE 9.2 i586 RPM: <a href="http://arg0.net/users/vgough/download/rlog-1.3.7-1suse92.i586.rpm">rlog-1.3.7-1suse92.i586.rpm</a></li><li>RedHat 7.3 i386 RPM: <a href="http://arg0.net/users/vgough/download/rlog-1.3.7-1rh73.i386.rpm">rlog-1.3.7-1rh73.i386.rpm</a></li></ul>
<p>
To check the signature, you can download my public key from a public key server, or from the link at the top of <a href="http://arg0.net/users/vgough">my homepage</a>.<p>
If you wish to be notified automatically of new releases, you can subscribe to new release notifications on the <a href="http://freshmeat.net/projects/rlog/">Freshmeat page</a>. <hr size="1"><address style="align: right;"><small>Generated on Mon Nov 20 22:57:44 2006 for rlog by&nbsp;
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.0 </small></address>
</body>
</html>