Branch data Line data Source code
1 : : /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2 : : /*************************************************************************
3 : : *
4 : : * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
5 : : *
6 : : * Copyright 2000, 2010 Oracle and/or its affiliates.
7 : : *
8 : : * OpenOffice.org - a multi-platform office productivity suite
9 : : *
10 : : * This file is part of OpenOffice.org.
11 : : *
12 : : * OpenOffice.org is free software: you can redistribute it and/or modify
13 : : * it under the terms of the GNU Lesser General Public License version 3
14 : : * only, as published by the Free Software Foundation.
15 : : *
16 : : * OpenOffice.org is distributed in the hope that it will be useful,
17 : : * but WITHOUT ANY WARRANTY; without even the implied warranty of
18 : : * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 : : * GNU Lesser General Public License version 3 for more details
20 : : * (a copy is included in the LICENSE file that accompanied this code).
21 : : *
22 : : * You should have received a copy of the GNU Lesser General Public License
23 : : * version 3 along with OpenOffice.org. If not, see
24 : : * <http://www.openoffice.org/license.html>
25 : : * for a copy of the LGPLv3 License.
26 : : *
27 : : ************************************************************************/
28 : : #ifndef _RTL_LOGFILE_HXX_
29 : : #define _RTL_LOGFILE_HXX_
30 : :
31 : : #include <rtl/logfile.h>
32 : : #include <rtl/string.hxx>
33 : :
34 : : namespace rtl
35 : : {
36 : : /**
37 : : @descr The intended use for class Logfile is to write time stamp information
38 : : for profiling purposes.
39 : :
40 : : Profiling output should only be generated for a special product version of OpenOffice
41 : : which is compiled with a defined preprocessor symbol 'TIMELOG'.
42 : : Therefore we have provided a set of macros that uses the class Logfile only if
43 : : this symbol is defined. If the macros are not sufficient, i.e. you need more
44 : : then three arguments for a printf style message, then you have to insert an
45 : : \#ifdef TIMELOG/\#endif brace yourself.
46 : :
47 : : Additionally the environment variable RTL_LOGFILE has to be defined in order to generate
48 : : logging information. If the variable is not empty, it creates a file with the name
49 : : $(RTL_LOGFILE)_$(PID).log, where $(PID) is the process id of the running process.
50 : : It can be used as a run time switch for enabling or disabling the logging.
51 : : Note that this variable is evaluated only once at the first attempt to write a message.
52 : :
53 : : The class LogFile collects runtime data within its constructor and destructor. It can be
54 : : used for timing whole functions.
55 : : If you want to write timing data without context you can use the RTL_LOGFILE_TRACE-macros
56 : : which are defined inside <rtl/logfile.h>.
57 : :
58 : : The class LogFile should not be used directly, instead use the RTL_LOGFILE_CONTEXT/
59 : : RTL_LOGFILE_TRACE-macros.
60 : :
61 : : Macro usage:
62 : : ------------
63 : : RTL_LOGFILE_CONTEXT( instance, name );
64 : : This macro creates an instance of class LogFile with the name "instance" and writes the current time,
65 : : thread id and "name" to the log file.
66 : :
67 : : Example: RTL_LOGFILE_CONTEXT( aLog, "Timing for foo-method" );
68 : :
69 : : RTL_LOGFILE_CONTEXT_TRACE( instance, mesage );
70 : : RTL_LOGFILE_CONTEXT_TRACEn( instance, frmt, arg1, .., arg3 );
71 : : These macros can be used to log information in a "instance" context. The "instance" object
72 : : is used to log message informations. All macros with "frmt" uses printf notation to log timing infos.
73 : :
74 : : Example: RTL_LOGFILE_CONTEXT_TRACE( aLog, "Now we call an expensive function" );
75 : : RTL_LOGFIlE_CONTEXT_TRACE1( aLog, "Config entries read: %u", (unsigned short)i );
76 : :
77 : : RTL_LOGFILE_TRACE( string );
78 : : RTL_LOGFILE_TRACEn( frmt, arg1, .., arg3 );
79 : : These macros can be used to log information outside a context. The macro directly calls
80 : : rtl_logfile_trace to write the info to the log file. All macros with "frmt" uses printf
81 : : notation to log timing infos.
82 : :
83 : : Example: RTL_LOGFILE_TRACE( "Timing for loading a file" );
84 : : RTL_LOGFILE_TRACE1( aLog, "Timing for loading file: %s", aFileName );
85 : :
86 : : The lines written to the log file consist of the following space separated elements:
87 : : 1. The time relative to the start of the global timer in milliseconds. The times is
88 : : started typically for the first logged line.
89 : : 2. Thread id. It's absolut value is probably of less interest than providing a way to
90 : : distinguish different threads.
91 : : 3. a. An opening or closing curly brace indicating the start or end of a scope.
92 : : 4a. Function name or general scope identifier.
93 : : b. A vertical line indicating an arbitrary message.
94 : : 4b optional function name or general scope identifier.
95 : : 5b A colon followed by a space and a free form message terminated by a newline.
96 : :
97 : : There is a second version of creating a context. RTL_LOGFILE_CONTEXT_AUTHOR takes
98 : : two more arguments, the name of the project and the author's sign who is responsible
99 : : for the code in which the macro is used.
100 : : */
101 : : class Logfile
102 : : {
103 : : public:
104 : : inline Logfile( const sal_Char *name );
105 : : /** @descr Create a log file context where the message field consists of a project
106 : : name, the author's shortcut, and the actual message. These three strings
107 : : are written in a format that is understood by script that later parses the
108 : : log file and that so can extract the three strings.
109 : : @param project Short name of the project, like sw for writer or sc for calc.
110 : : @param author The sign of the person responsible for the code.
111 : : @param name The actual message, typically a method name.
112 : : */
113 : : inline Logfile( const sal_Char *project, const sal_Char *author, const sal_Char *name );
114 : : inline ~Logfile();
115 : : inline const sal_Char *getName();
116 : : private:
117 : : ::rtl::OString m_sName;
118 : : };
119 : :
120 : 11699 : inline Logfile::Logfile( const sal_Char *name )
121 : 11699 : : m_sName( name )
122 : : {
123 [ + - ]: 11699 : rtl_logfile_longTrace( "{ %s\n", name );
124 : 11699 : }
125 : :
126 : : inline Logfile::Logfile( const sal_Char *project, const sal_Char *author, const sal_Char *name )
127 : : : m_sName( project)
128 : : {
129 : : m_sName += " (";
130 : : m_sName += author;
131 : : m_sName += ") ";
132 : : m_sName += name;
133 : : rtl_logfile_longTrace( "{ %s\n", m_sName.pData->buffer );
134 : : }
135 : :
136 : 11699 : inline Logfile::~Logfile()
137 : : {
138 [ + - ]: 11699 : rtl_logfile_longTrace( "} %s\n", m_sName.pData->buffer );
139 : 11699 : }
140 : :
141 : 0 : inline const sal_Char * Logfile::getName()
142 : : {
143 : 0 : return m_sName.getStr();
144 : : }
145 : : }
146 : :
147 : : #ifdef TIMELOG
148 : : #define RTL_LOGFILE_CONTEXT( instance, name ) ::rtl::Logfile instance( name )
149 : : #define RTL_LOGFILE_CONTEXT_AUTHOR( instance, project, author, name ) ::rtl::Logfile instance(project, author, name )
150 : : #define RTL_LOGFILE_CONTEXT_TRACE( instance, message ) \
151 : : rtl_logfile_longTrace( "| %s : %s\n", \
152 : : instance.getName(), \
153 : : message )
154 : : #define RTL_LOGFILE_CONTEXT_TRACE1( instance , frmt, arg1 ) \
155 : : rtl_logfile_longTrace( "| %s : ", \
156 : : instance.getName() ); \
157 : : rtl_logfile_trace( frmt , arg1 ); \
158 : : rtl_logfile_trace( "\n" )
159 : : #define RTL_LOGFILE_CONTEXT_TRACE2( instance , frmt, arg1 , arg2 ) \
160 : : rtl_logfile_longTrace( "| %s : ", \
161 : : instance.getName() ); \
162 : : rtl_logfile_trace( frmt , arg1 , arg2 ); \
163 : : rtl_logfile_trace( "\n" )
164 : : #define RTL_LOGFILE_CONTEXT_TRACE3( instance , frmt, arg1 , arg2 , arg3 ) \
165 : : rtl_logfile_longTrace( "| %s : ", \
166 : : instance.getName() ); \
167 : : rtl_logfile_trace( frmt , arg1 , arg2 , arg3 ); \
168 : : rtl_logfile_trace( "\n" )
169 : :
170 : : #else
171 : : #define RTL_LOGFILE_CONTEXT( instance, name ) ((void)0)
172 : : #define RTL_LOGFILE_CONTEXT_AUTHOR( instance, project, author, name ) ((void)0)
173 : : #define RTL_LOGFILE_CONTEXT_TRACE( instance, message ) ((void)0)
174 : : #define RTL_LOGFILE_CONTEXT_TRACE1( instance, frmt, arg1 ) ((void)0)
175 : : #define RTL_LOGFILE_CONTEXT_TRACE2( instance, frmt, arg1, arg2 ) ((void)0)
176 : : #define RTL_LOGFILE_CONTEXT_TRACE3( instance, frmt, arg1, arg2 , arg3 ) ((void)0)
177 : : #endif
178 : :
179 : : // Normal RTL_LOGFILE_* entries will not make it into release versions,
180 : : // TIMELOG is disabled a few versions prior relase build.
181 : : //
182 : : // We need some logs also in these builds, eg. for making performance regression tests.
183 : : //
184 : : // POLICY: Don't use RTL_LOGFILE_PRODUCT_* for your personal logging information.
185 : : // Be aware that these logs make it into the product shipped to customers.
186 : : // If you have good reasons for doing this, please contact product management.
187 : :
188 : : #define RTL_LOGFILE_PRODUCT_TRACE( string ) \
189 : : rtl_logfile_longTrace( "| : %s\n", string )
190 : : #define RTL_LOGFILE_PRODUCT_TRACE1( frmt, arg1 ) \
191 : : rtl_logfile_longTrace( "| : " ); \
192 : : rtl_logfile_trace( frmt, arg1 ); \
193 : : rtl_logfile_trace( "\n" )
194 : : #define RTL_LOGFILE_PRODUCT_CONTEXT( instance, name ) \
195 : : ::rtl::Logfile instance( name )
196 : : #define RTL_LOGFILE_PRODUCT_CONTEXT_TRACE1( instance, frmt, arg1 ) \
197 : : rtl_logfile_longTrace( "| %s : ", \
198 : : instance.getName() ); \
199 : : rtl_logfile_trace( frmt, arg1 ); \
200 : : rtl_logfile_trace( "\n" )
201 : : #define RTL_LOGFILE_HASLOGFILE() \
202 : : rtl_logfile_hasLogFile()
203 : :
204 : :
205 : : #endif
206 : :
207 : : /* vim:set shiftwidth=4 softtabstop=4 expandtab: */
|
