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