dali/public-api/common/dali-common.h

   1 #ifndef DALI_COMMON_H
   2 #define DALI_COMMON_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
  23 /*
  24  * Definitions for shared library support.
  25  *
  26  * If a library is built with -DENABLE_EXPORTALL=ON or -DENABLE_DEBUG=ON
  27  * then HIDE_DALI_INTERNALS is not defined, and nothing is hidden.
  28  * If it is built without these options (the default), then HIDE_INTERNALS
  29  * is defined when building the library, visibility is automatically hidden, and the explicit
  30  * defines below come into use.
  31  * When building a library that uses DALI, HIDE_DALI_INTERNALS.
  32  */
  33 #if __GNUC__ >= 4
  34 #  ifndef HIDE_DALI_INTERNALS
  35 #    define DALI_EXPORT_API
  36 #    define DALI_IMPORT_API
  37 #    define DALI_CORE_API
  38 #    define DALI_INTERNAL
  39 #  else
  40 #    define DALI_EXPORT_API __attribute__ ((visibility ("default")))
  41 #    define DALI_IMPORT_API __attribute__ ((visibility ("default")))
  42 #    define DALI_CORE_API   __attribute__ ((visibility ("default")))
  43 #    define DALI_INTERNAL   __attribute__ ((visibility ("hidden")))
  44 #  endif
  45 #else
  46 #ifdef WIN32
  47  /** Visibility attribute to show declarations */
  48 #  define DALI_EXPORT_API __declspec(dllexport)
  49
  50 #ifdef BUILDING_DALI_CORE
  51  /** Visibility attribute to hide declarations */
  52 #  define DALI_CORE_API __declspec(dllexport)
  53 #else
  54 /** Visibility attribute to hide declarations */
  55 #  define DALI_CORE_API __declspec(dllimport)
  56 #endif
  57
  58 #else
  59  /** Visibility attribute to show declarations */
  60 #  define DALI_EXPORT_API
  61 /** Visibility attribute to show declarations */
  62 #  define DALI_IMPORT_API
  63 /** Visibility attribute to show declarations */
  64 #  define DALI_CORE_API
  65 #endif
  66 /** Visibility attribute to hide declarations */
  67 #  define DALI_INTERNAL
  68 #endif
  69
  70 #ifdef DEPRECATION_WARNING
  71 #define DALI_DEPRECATED_API __attribute__((__visibility__("default"), deprecated))
  72 #else
  73 #define DALI_DEPRECATED_API
  74 #endif
  75
  76 #if defined (__GXX_EXPERIMENTAL_CXX0X__) || (__cplusplus >= 201103L)
  77 // C++0x support
  78 #define _CPP11
  79 #else
  80 // C++0x not supported
  81 #endif
  82
  83 /**
  84  * @brief Two macros to provide branch predictor information.
  85  * DALI_LIKELY should be used when a branch is taken in almost all cases so the
  86  * branch predictor can avoid pre-fetching. The code for else branch
  87  * DALI_UNLIKELY should be used when a branch is almost never taken.
  88  * @SINCE_1_0.0
  89  */
  90 #ifdef __GNUC
  91 #define DALI_LIKELY(expression)   __builtin_expect( !!(expression), 1 )
  92 #define DALI_UNLIKELY(expression) __builtin_expect( !!(expression), 0 )
  93 #else
  94 #define DALI_LIKELY(expression)   !!(expression)
  95 #define DALI_UNLIKELY(expression) !!(expression)
  96 #endif
  97
  98 /**
  99  * @brief The DALi namespace.
 100  * @SINCE_1_0.0
 101  */
 102 namespace Dali
 103 {
 104 /**
 105  * @addtogroup dali_core_common
 106  * @{
 107  */
 108
 109 /**
 110  * @brief Method to log assertion message in DALI_ASSERT_ALWAYS macro below.
 111  *
 112  * @SINCE_1_0.0
 113  * @param[in] location Where the assertion occurred
 114  * @param[in] condition The assertion condition
 115  */
 116 DALI_CORE_API void DaliAssertMessage( const char* location, const char* condition );
 117
 118 /**
 119  * @brief Exception class for Dali Core library - Raised by assertions in codebase.
 120  * @SINCE_1_0.0
 121  */
 122 class DALI_CORE_API DaliException
 123 {
 124 public:
 125   /**
 126    * @brief Constructor.
 127    *
 128    * Will always display a backtrace when raised in a debug build.
 129    *
 130    * @SINCE_1_0.0
 131    * @param[in] location The location of the assertion
 132    * @param[in] condition The assertion condition
 133    */
 134   DaliException( const char* location, const char* condition );
 135
 136   const char* location;
 137   const char* condition;
 138 };
 139
 140 /**
 141  * @}
 142  */
 143 }// Dali
 144
 145 /**
 146  * @brief An invariant concurrent assertion to ensure its argument always evaluates TRUE.
 147  *
 148  * Use this for rules that must always be true regardless of build options.
 149  * For example, Actor must only ever have one parent.
 150  * To be clear, this test remains compiled into release builds that are deployed
 151  * on the platform.
 152  * Semantically, a failure of this test is signalling that dali is giving up and
 153  * quitting.
 154  * Since we don't catch the exception, a failure on any thread other than event
 155  * will propagate up the call stack and kill that thread.
 156  * A failure on the event thread may give the application an opportunity to
 157  * recover if there is an application-written exception handler on the call
 158  * stack between the throw site and the thread root and the application is built
 159  * with a compatible ABI.
 160  * Handle this macro with care at the level you would if it expanded to:
 161  *    if(!cond) { exit(EXIT_FAILURE); }
 162  * (which it is often equivalent to in effect).
 163  * It should not be used for simple parameter validation for instance.
 164  */
 165
 166 /**
 167  * @brief Strip assert location for release builds, assert text is descriptive enough.
 168  * This is to save space for low spec devices.
 169  * @SINCE_1_0.0
 170  */
 171 #if defined(DEBUG_ENABLED)
 172 #if defined(WIN32)
 173 #define ASSERT_LOCATION __FUNCSIG__
 174 #else
 175 #define ASSERT_LOCATION __PRETTY_FUNCTION__
 176 #endif
 177 #else
 178 #define ASSERT_LOCATION NULL
 179 #endif
 180
 181 #define DALI_ASSERT_ALWAYS(cond)                \
 182   if(DALI_UNLIKELY(!(cond))) \
 183   { \
 184     Dali::DaliAssertMessage( ASSERT_LOCATION, #cond );   \
 185     throw Dali::DaliException( ASSERT_LOCATION, #cond );  \
 186   }
 187
 188 #define DALI_ABORT(message)                \
 189   { \
 190     Dali::DaliAssertMessage( ASSERT_LOCATION, message );   \
 191     throw Dali::DaliException( ASSERT_LOCATION, message );  \
 192   }
 193
 194 /**
 195  * @brief An invariant concurrent assertion to ensure its argument evaluates TRUE in debug builds.
 196  *
 197  * Use this to sanity check algorithms and prevent internal programming errors.
 198  * @SINCE_1_0.0
 199  */
 200 #if defined(DEBUG_ENABLED)
 201 #define DALI_ASSERT_DEBUG(cond) DALI_ASSERT_ALWAYS(cond)
 202 #else
 203 #define DALI_ASSERT_DEBUG(cond)
 204 #endif
 205
 206 /// Use DALI_FALLTHROUGH in switch statements where one case is supposed to fall through into another case
 207 #if __has_cpp_attribute(fallthrough)
 208 #define DALI_FALLTHROUGH [[fallthrough]]
 209 #else
 210 #define DALI_FALLTHROUGH
 211 #endif
 212
 213 #endif // DALI_COMMON_H