dali/integration-api/trace.h

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