1 #ifndef DALI_INTEGRATION_TRACE_H
2 #define DALI_INTEGRATION_TRACE_H
5 * Copyright (c) 2023 Samsung Electronics Co., Ltd.
7 * Licensed under the Apache License, Version 2.0 (the "License");
8 * you may not use this file except in compliance with the License.
9 * You may obtain a copy of the License at
11 * http://www.apache.org/licenses/LICENSE-2.0
13 * Unless required by applicable law or agreed to in writing, software
14 * distributed under the License is distributed on an "AS IS" BASIS,
15 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 * See the License for the specific language governing permissions and
17 * limitations under the License.
25 #include <dali/public-api/common/dali-common.h>
34 * Used by tracing macros to log a context message
35 * @param[in] start a bool to indicate start (true) or end (false) of the tracing / logging
36 * @param[in] tag a unique event tag name
37 * @param[in] message an additional message for this trace. Ignore if it is nullptr
39 DALI_CORE_API void LogContext(bool start, const char* tag, const char* message = nullptr);
42 * typedef for the LogContextFunction function.
44 using LogContextFunction = void (*)(bool, const char*, const char*);
47 * A LogContextFunction function has to be installed for every thread that wants to use tracing.
48 * This should be done by the adaptor.
49 * The LogContextFunction function can be different for each thread.
50 * @param LogContextFunction the Log Context function to install
52 DALI_CORE_API void InstallLogContextFunction(const LogContextFunction& logContextFunction);
54 /********************************************************************************
56 ********************************************************************************/
61 * The Filter object is used by the DALI_TRACE_BEGIN macro and others to determine if the tracing
62 * should take place, and routes the tracing via the platform abstraction's LogMessage.
64 * It provides the ability to turn tracing on or off.
67 class DALI_CORE_API Filter
71 * Test if trace is enabled for this filter.
72 * @return true if trace is enabled;
74 inline bool IsTraceEnabled()
80 * Enable tracing on this filter.
82 inline void EnableTrace()
88 * Disable tracing on this filter.
90 inline void DisableTrace()
92 mTraceEnabled = false;
96 * Create a new filter whose trace can be modified through the use of an environment variable.
98 * @param[in] trace The default trace level. If true, function tracing is on.
99 * @param[in] environmentVariableName The environment variable name used in order to change the trace.
101 * @info To modify trace at runtime, you should define your filter as shown below:
104 * Trace::Filter* filter = Trace::Filter::New( false, "TRACE_ENV" );
107 * And to use it when running an executable:
109 * TRACE_ENV=1 dali-demo // Trace ON
110 * TRACE_ENV=0 dali-demo // Trace OFF
113 static Filter* New(bool trace, const char* environmentVariableName);
117 * @param[in] tagName - a unique event tag name.
119 void BeginTrace(const char* tagName);
123 * @param[in] tagName - a unique event tag name.
124 * @param[in] message - an additional message for this trace if needs.
126 void BeginTrace(const char* tagName, const char* message);
130 * @param[in] tagName - a unique event tag name.
132 void EndTrace(const char* tagName);
136 * @param[in] tagName - a unique event tag name.
137 * @param[in] message - an additional message for this trace if needs.
139 void EndTrace(const char* tagName, const char* message);
142 * Enable trace on all filters.
144 static void EnableGlobalTrace();
147 * Disable trace on all filters.
149 static void DisableGlobalTrace();
154 * @param[in] trace - whether this filter allows tracing.
157 : mTraceEnabled(trace)
165 /********************************************************************************
167 ********************************************************************************/
170 * These macros allow the instrumentation of methods.
174 * The Tracer object is used by the DALI_TRACE_SCOPE and DALI_TRACE_FUNCTION macros
175 * and uses filter object which in tun routes the tracing via the platform abstraction's LogMessage.
178 class DALI_CORE_API Tracer final
181 Tracer(Filter* filter, const char* tag);
190 * For initialization of trace filter, please use DALI_INIT_TRACE_FILTER macro i.e. DALI_INIT_TRACE_FILTER( gFilter, "TRACE_COMBINED", true );
191 * To start tracing, please use DALI_TRACE_BEGIN macro i.e. DALI_TRACE_BEGIN( gFilter, "RENDERING" );
192 * To end tracing, please use DALI_TRACE_END macro i.e. DALI_TRACE_END( gFilter, "RENDERING" );
193 * For scoped tracing, please use DALI_TRACE_SCOPE macro i.e. DALI_TRACE_SCOPE( gFilter, "RENDERING" );
194 * For function tracing, please use DALI_TRACE_FUNCTION macro i.e. DALI_TRACE_FUNCTION( gFilter );
198 * Initialization of trace filter
201 #define DALI_INIT_TRACE_FILTER(name, environmentVariableName, enable) \
204 Dali::Integration::Trace::Filter* name = Dali::Integration::Trace::Filter::New(enable, #environmentVariableName); \
210 #define DALI_TRACE_BEGIN(filter, tag) \
211 if(filter && filter->IsTraceEnabled()) \
213 filter->BeginTrace(tag); \
216 #define DALI_TRACE_BEGIN_WITH_MESSAGE(filter, tag, message) \
217 if(filter && filter->IsTraceEnabled()) \
219 filter->BeginTrace(tag, message); \
222 #define DALI_TRACE_BEGIN_WITH_MESSAGE_GENERATOR(filter, tag, messageGenerator) \
223 if(filter && filter->IsTraceEnabled()) \
225 std::ostringstream oss; \
226 messageGenerator(oss); \
227 filter->BeginTrace(tag, oss.str().c_str()); \
233 #define DALI_TRACE_END(filter, tag) \
234 if(filter && filter->IsTraceEnabled()) \
236 filter->EndTrace(tag); \
239 #define DALI_TRACE_END_WITH_MESSAGE(filter, tag, message) \
240 if(filter && filter->IsTraceEnabled()) \
242 filter->EndTrace(tag, message); \
245 #define DALI_TRACE_END_WITH_MESSAGE_GENERATOR(filter, tag, messageGenerator) \
246 if(filter && filter->IsTraceEnabled()) \
248 std::ostringstream oss; \
249 messageGenerator(oss); \
250 filter->EndTrace(tag, oss.str().c_str()); \
254 * Used for function tracing. It logs tracing of the fuction from start to end.
256 #define DALI_TRACE_FUNCTION(filter) \
257 Dali::Integration::Trace::Tracer logTraceFunction(filter, ASSERT_LOCATION);
260 * Used for scope tracing. It logs tracing around a scope.
262 #define DALI_TRACE_SCOPE(filter, tag) \
263 Dali::Integration::Trace::Tracer logTracerScope(filter, tag);
265 #else // TRACE_ENABLED
267 #define DALI_INIT_TRACE_FILTER(name, tag, enable)
268 #define DALI_TRACE_BEGIN(filter, tag)
269 #define DALI_TRACE_BEGIN_WITH_MESSAGE(filter, tag, message)
270 #define DALI_TRACE_BEGIN_WITH_MESSAGE_GENERATOR(filter, tag, messageGenerator)
271 #define DALI_TRACE_END(filter, tag)
272 #define DALI_TRACE_END_WITH_MESSAGE(filter, tag, message)
273 #define DALI_TRACE_END_WITH_MESSAGE_GENERATOR(filter, tag, messageGenerator)
274 #define DALI_TRACE_FUNCTION(filter)
275 #define DALI_TRACE_SCOPE(filter, tag)
281 } // namespace Integration
285 #endif // DALI_INTEGRATION_TRACE_H