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