1 // 2 // Copyright 2017 The Abseil Authors. 3 // 4 // Licensed under the Apache License, Version 2.0 (the "License"); 5 // you may not use this file except in compliance with the License. 6 // You may obtain a copy of the License at 7 // 8 // https://www.apache.org/licenses/LICENSE-2.0 9 // 10 // Unless required by applicable law or agreed to in writing, software 11 // distributed under the License is distributed on an "AS IS" BASIS, 12 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 // See the License for the specific language governing permissions and 14 // limitations under the License. 15 // 16 // ----------------------------------------------------------------------------- 17 // File: macros.h 18 // ----------------------------------------------------------------------------- 19 // 20 // This header file defines the set of language macros used within Abseil code. 21 // For the set of macros used to determine supported compilers and platforms, 22 // see absl/base/config.h instead. 23 // 24 // This code is compiled directly on many platforms, including client 25 // platforms like Windows, Mac, and embedded systems. Before making 26 // any changes here, make sure that you're not breaking any platforms. 27 28 #ifndef ABSL_BASE_MACROS_H_ 29 #define ABSL_BASE_MACROS_H_ 30 31 #include <cassert> 32 #include <cstddef> 33 34 #include "absl/base/attributes.h" 35 #include "absl/base/optimization.h" 36 #include "absl/base/port.h" 37 38 // ABSL_ARRAYSIZE() 39 // 40 // Returns the number of elements in an array as a compile-time constant, which 41 // can be used in defining new arrays. If you use this macro on a pointer by 42 // mistake, you will get a compile-time error. 43 #define ABSL_ARRAYSIZE(array) \ 44 (sizeof(::absl::macros_internal::ArraySizeHelper(array))) 45 46 namespace absl { 47 ABSL_NAMESPACE_BEGIN 48 namespace macros_internal { 49 // Note: this internal template function declaration is used by ABSL_ARRAYSIZE. 50 // The function doesn't need a definition, as we only use its type. 51 template <typename T, size_t N> 52 auto ArraySizeHelper(const T (&array)[N]) -> char (&)[N]; 53 } // namespace macros_internal 54 ABSL_NAMESPACE_END 55 } // namespace absl 56 57 // kLinkerInitialized 58 // 59 // An enum used only as a constructor argument to indicate that a variable has 60 // static storage duration, and that the constructor should do nothing to its 61 // state. Use of this macro indicates to the reader that it is legal to 62 // declare a static instance of the class, provided the constructor is given 63 // the absl::base_internal::kLinkerInitialized argument. 64 // 65 // Normally, it is unsafe to declare a static variable that has a constructor or 66 // a destructor because invocation order is undefined. However, if the type can 67 // be zero-initialized (which the loader does for static variables) into a valid 68 // state and the type's destructor does not affect storage, then a constructor 69 // for static initialization can be declared. 70 // 71 // Example: 72 // // Declaration 73 // explicit MyClass(absl::base_internal:LinkerInitialized x) {} 74 // 75 // // Invocation 76 // static MyClass my_global(absl::base_internal::kLinkerInitialized); 77 namespace absl { 78 ABSL_NAMESPACE_BEGIN 79 namespace base_internal { 80 enum LinkerInitialized { 81 kLinkerInitialized = 0, 82 }; 83 } // namespace base_internal 84 ABSL_NAMESPACE_END 85 } // namespace absl 86 87 // ABSL_FALLTHROUGH_INTENDED 88 // 89 // Annotates implicit fall-through between switch labels, allowing a case to 90 // indicate intentional fallthrough and turn off warnings about any lack of a 91 // `break` statement. The ABSL_FALLTHROUGH_INTENDED macro should be followed by 92 // a semicolon and can be used in most places where `break` can, provided that 93 // no statements exist between it and the next switch label. 94 // 95 // Example: 96 // 97 // switch (x) { 98 // case 40: 99 // case 41: 100 // if (truth_is_out_there) { 101 // ++x; 102 // ABSL_FALLTHROUGH_INTENDED; // Use instead of/along with annotations 103 // // in comments 104 // } else { 105 // return x; 106 // } 107 // case 42: 108 // ... 109 // 110 // Notes: when compiled with clang in C++11 mode, the ABSL_FALLTHROUGH_INTENDED 111 // macro is expanded to the [[clang::fallthrough]] attribute, which is analysed 112 // when performing switch labels fall-through diagnostic 113 // (`-Wimplicit-fallthrough`). See clang documentation on language extensions 114 // for details: 115 // https://clang.llvm.org/docs/AttributeReference.html#fallthrough-clang-fallthrough 116 // 117 // When used with unsupported compilers, the ABSL_FALLTHROUGH_INTENDED macro 118 // has no effect on diagnostics. In any case this macro has no effect on runtime 119 // behavior and performance of code. 120 #ifdef ABSL_FALLTHROUGH_INTENDED 121 #error "ABSL_FALLTHROUGH_INTENDED should not be defined." 122 #endif 123 124 // TODO(zhangxy): Use c++17 standard [[fallthrough]] macro, when supported. 125 #if defined(__clang__) && defined(__has_warning) 126 #if __has_feature(cxx_attributes) && __has_warning("-Wimplicit-fallthrough") 127 #define ABSL_FALLTHROUGH_INTENDED [[clang::fallthrough]] 128 #endif 129 #elif defined(__GNUC__) && __GNUC__ >= 7 130 #define ABSL_FALLTHROUGH_INTENDED [[gnu::fallthrough]] 131 #endif 132 133 #ifndef ABSL_FALLTHROUGH_INTENDED 134 #define ABSL_FALLTHROUGH_INTENDED \ 135 do { \ 136 } while (0) 137 #endif 138 139 // ABSL_DEPRECATED() 140 // 141 // Marks a deprecated class, struct, enum, function, method and variable 142 // declarations. The macro argument is used as a custom diagnostic message (e.g. 143 // suggestion of a better alternative). 144 // 145 // Examples: 146 // 147 // class ABSL_DEPRECATED("Use Bar instead") Foo {...}; 148 // 149 // ABSL_DEPRECATED("Use Baz() instead") void Bar() {...} 150 // 151 // template <typename T> 152 // ABSL_DEPRECATED("Use DoThat() instead") 153 // void DoThis(); 154 // 155 // Every usage of a deprecated entity will trigger a warning when compiled with 156 // clang's `-Wdeprecated-declarations` option. This option is turned off by 157 // default, but the warnings will be reported by clang-tidy. 158 #if defined(__clang__) && __cplusplus >= 201103L 159 #define ABSL_DEPRECATED(message) __attribute__((deprecated(message))) 160 #endif 161 162 #ifndef ABSL_DEPRECATED 163 #define ABSL_DEPRECATED(message) 164 #endif 165 166 // ABSL_BAD_CALL_IF() 167 // 168 // Used on a function overload to trap bad calls: any call that matches the 169 // overload will cause a compile-time error. This macro uses a clang-specific 170 // "enable_if" attribute, as described at 171 // https://clang.llvm.org/docs/AttributeReference.html#enable-if 172 // 173 // Overloads which use this macro should be bracketed by 174 // `#ifdef ABSL_BAD_CALL_IF`. 175 // 176 // Example: 177 // 178 // int isdigit(int c); 179 // #ifdef ABSL_BAD_CALL_IF 180 // int isdigit(int c) 181 // ABSL_BAD_CALL_IF(c <= -1 || c > 255, 182 // "'c' must have the value of an unsigned char or EOF"); 183 // #endif // ABSL_BAD_CALL_IF 184 #if ABSL_HAVE_ATTRIBUTE(enable_if) 185 #define ABSL_BAD_CALL_IF(expr, msg) \ 186 __attribute__((enable_if(expr, "Bad call trap"), unavailable(msg))) 187 #endif 188 189 // ABSL_ASSERT() 190 // 191 // In C++11, `assert` can't be used portably within constexpr functions. 192 // ABSL_ASSERT functions as a runtime assert but works in C++11 constexpr 193 // functions. Example: 194 // 195 // constexpr double Divide(double a, double b) { 196 // return ABSL_ASSERT(b != 0), a / b; 197 // } 198 // 199 // This macro is inspired by 200 // https://akrzemi1.wordpress.com/2017/05/18/asserts-in-constexpr-functions/ 201 #if defined(NDEBUG) 202 #define ABSL_ASSERT(expr) \ 203 (false ? static_cast<void>(expr) : static_cast<void>(0)) 204 #else 205 #define ABSL_ASSERT(expr) \ 206 (ABSL_PREDICT_TRUE((expr)) ? static_cast<void>(0) \ 207 : [] { assert(false && #expr); }()) // NOLINT 208 #endif 209 210 #ifdef ABSL_HAVE_EXCEPTIONS 211 #define ABSL_INTERNAL_TRY try 212 #define ABSL_INTERNAL_CATCH_ANY catch (...) 213 #define ABSL_INTERNAL_RETHROW do { throw; } while (false) 214 #else // ABSL_HAVE_EXCEPTIONS 215 #define ABSL_INTERNAL_TRY if (true) 216 #define ABSL_INTERNAL_CATCH_ANY else if (false) 217 #define ABSL_INTERNAL_RETHROW do {} while (false) 218 #endif // ABSL_HAVE_EXCEPTIONS 219 220 #endif // ABSL_BASE_MACROS_H_ 221