dali/integration-api/trace.h

   1 #ifndef DALI_INTEGRATION_TRACE_H
   2 #define DALI_INTEGRATION_TRACE_H
   3
   4 /*
   5  * Copyright (c) 2020 Samsung Electronics Co., Ltd.
   6  *
   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
  10  *
  11  * http://www.apache.org/licenses/LICENSE-2.0
  12  *
  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.
  18  *
  19  */
  20
  21 // EXTERNAL INCLUDES
  22 #include <string>
  23
  24 // INTERNAL INCLUDES
  25 #include <dali/public-api/common/dali-common.h>
  26
  27 namespace Dali
  28 {
  29 namespace Integration
  30 {
  31 namespace Trace
  32 {
  33 /**
  34  * Used by tracing macros to log a context message
  35  * @param start a bool to indicate start (true) or end (false) of the tracing / logging
  36  * @param tag a unique event tag name
  37  */
  38 DALI_CORE_API void LogContext(bool start, const char* tag);
  39
  40 /**
  41  * typedef for the LogContextFunction function.
  42  */
  43 using LogContextFunction = void (*)(bool, const char*);
  44
  45 /**
  46  * A LogContextFunction function has to be installed for every thread that wants to use tracing.
  47  * This should be done by the adaptor.
  48  * The LogContextFunction function can be different for each thread.
  49  * @param LogContextFunction the Log Context function to install
  50  */
  51 DALI_CORE_API void InstallLogContextFunction(const LogContextFunction& logContextFunction);
  52
  53 /********************************************************************************
  54  *                                    Filter                                    *
  55  ********************************************************************************/
  56
  57 #ifdef TRACE_ENABLED
  58
  59 /**
  60  * The Filter object is used by the DALI_TRACE_BEGIN macro and others to determine if the tracing
  61  * should take place, and routes the tracing via the platform abstraction's LogMessage.
  62  *
  63  * It provides the ability to turn tracing on or off.
  64  *
  65  */
  66 class DALI_CORE_API Filter
  67 {
  68 public:
  69   /**
  70    * Test if trace is enabled for this filter.
  71    * @return true if trace is enabled;
  72    */
  73   inline bool IsTraceEnabled()
  74   {
  75     return mTraceEnabled;
  76   }
  77
  78   /**
  79    * Enable tracing on this filter.
  80    */
  81   inline void EnableTrace()
  82   {
  83     mTraceEnabled = true;
  84   }
  85
  86   /**
  87    * Disable tracing on this filter.
  88    */
  89   inline void DisableTrace()
  90   {
  91     mTraceEnabled = false;
  92   }
  93
  94   /**
  95    * Create a new filter whose trace can be modified through the use of an environment variable.
  96    *
  97    * @param[in] trace The default trace level. If true, function tracing is on.
  98    * @param[in] environmentVariableName The environment variable name used in order to change the trace.
  99    *
 100    * @info To modify trace at runtime, you should define your filter as shown below:
 101    *
 102    * @code
 103    * Trace::Filter* filter = Trace::Filter::New( false, "TRACE_ENV" );
 104    * @endcode
 105    *
 106    * And to use it when running an executable:
 107    * @code
 108    * TRACE_ENV=1 dali-demo  // Trace ON
 109    * TRACE_ENV=0 dali-demo  // Trace OFF
 110    * @endcode
 111    */
 112   static Filter* New(bool trace, const char* environmentVariableName);
 113
 114   /**
 115    * Begin trace.
 116    * @param[in] tagName - a unique event tag name.
 117    */
 118   void BeginTrace(const char* tagName);
 119
 120   /**
 121    * End trace.
 122    * @param[in] tagName - a unique event tag name.
 123    */
 124   void EndTrace(const char* tagName);
 125
 126   /**
 127    * Enable trace on all filters.
 128    */
 129   static void EnableGlobalTrace();
 130
 131   /**
 132    * Disable trace on all filters.
 133    */
 134   static void DisableGlobalTrace();
 135
 136 private:
 137   /**
 138    * Constructor.
 139    * @param[in] trace - whether this filter allows tracing.
 140    */
 141   Filter(bool trace)
 142   : mTraceEnabled(trace)
 143   {
 144   }
 145
 146 private:
 147   bool mTraceEnabled;
 148 };
 149
 150 /********************************************************************************
 151  *                                  Trace Macros                                *
 152  ********************************************************************************/
 153
 154 /*
 155  * These macros allow the instrumentation of methods.
 156  */
 157
 158 /**
 159  * The Tracer object is used by the DALI_TRACE_SCOPE and DALI_TRACE_FUNCTION macros
 160  * and uses filter object which in tun routes the tracing via the platform abstraction's LogMessage.
 161  *
 162  */
 163 class DALI_CORE_API Tracer final
 164 {
 165 public:
 166   Tracer(Filter* filter, const char* tag);
 167   ~Tracer();
 168
 169 public:
 170   const char* mTag;
 171   Filter*     mFilter;
 172 };
 173
 174 /**
 175  * For initialization of trace filter, please use DALI_INIT_TRACE_FILTER macro i.e. DALI_INIT_TRACE_FILTER( gFilter, "TRACE_COMBINED", true );
 176  * To start tracing, please use DALI_TRACE_BEGIN macro i.e. DALI_TRACE_BEGIN( gFilter, "RENDERING" );
 177  * To end tracing, please use DALI_TRACE_END macro i.e. DALI_TRACE_END( gFilter, "RENDERING" );
 178  * For scoped tracing, please use DALI_TRACE_SCOPE macro i.e. DALI_TRACE_SCOPE( gFilter, "RENDERING" );
 179  * For function tracing, please use DALI_TRACE_FUNCTION macro i.e. DALI_TRACE_FUNCTION( gFilter );
 180  */
 181
 182 /**
 183  * Initialization of trace filter
 184  * @ref Filter::New
 185  */
 186 #define DALI_INIT_TRACE_FILTER(name, environmentVariableName, enable)                                               \
 187   namespace                                                                                                         \
 188   {                                                                                                                 \
 189   Dali::Integration::Trace::Filter* name = Dali::Integration::Trace::Filter::New(enable, #environmentVariableName); \
 190   }
 191
 192 /**
 193  * Start of tracing
 194  */
 195 #define DALI_TRACE_BEGIN(filter, tag)    \
 196   if(filter && filter->IsTraceEnabled()) \
 197   {                                      \
 198     filter->BeginTrace(tag);             \
 199   }
 200
 201 /**
 202  * End of tracing
 203  */
 204 #define DALI_TRACE_END(filter, tag)      \
 205   if(filter && filter->IsTraceEnabled()) \
 206   {                                      \
 207     filter->EndTrace(tag);               \
 208   }
 209
 210 /**
 211  * Used for function tracing. It logs tracing of the fuction from start to end.
 212  */
 213 #define DALI_TRACE_FUNCTION(filter) \
 214   Dali::Integration::Trace::Tracer logTraceFunction(filter, ASSERT_LOCATION);
 215
 216 /**
 217  * Used for scope tracing. It logs tracing around a scope.
 218  */
 219 #define DALI_TRACE_SCOPE(filter, tag) \
 220   Dali::Integration::Trace::Tracer logTracerScope(filter, tag);
 221
 222 #else // TRACE_ENABLED
 223
 224 #define DALI_INIT_TRACE_FILTER(name, tag, enable)
 225 #define DALI_TRACE_BEGIN(filter, tag)
 226 #define DALI_TRACE_END(filter, tag)
 227 #define DALI_TRACE_FUNCTION(filter)
 228 #define DALI_TRACE_SCOPE(filter, tag)
 229
 230 #endif
 231
 232 } // namespace Trace
 233
 234 } // namespace Integration
 235
 236 } // namespace Dali
 237
 238 #endif // DALI_INTEGRATION_TRACE_H