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/config.h" 36 #include "absl/base/optimization.h" 37 #include "absl/base/port.h" 38 39 // ABSL_ARRAYSIZE() 40 // 41 // Returns the number of elements in an array as a compile-time constant, which 42 // can be used in defining new arrays. If you use this macro on a pointer by 43 // mistake, you will get a compile-time error. 44 #define ABSL_ARRAYSIZE(array) \ 45 (sizeof(::absl::macros_internal::ArraySizeHelper(array))) 46 47 namespace absl { 48 ABSL_NAMESPACE_BEGIN 49 namespace macros_internal { 50 // Note: this internal template function declaration is used by ABSL_ARRAYSIZE. 51 // The function doesn't need a definition, as we only use its type. 52 template <typename T, size_t N> 53 auto ArraySizeHelper(const T (&array)[N]) -> char (&)[N]; 54 } // namespace macros_internal 55 ABSL_NAMESPACE_END 56 } // namespace absl 57 58 // ABSL_BAD_CALL_IF() 59 // 60 // Used on a function overload to trap bad calls: any call that matches the 61 // overload will cause a compile-time error. This macro uses a clang-specific 62 // "enable_if" attribute, as described at 63 // https://clang.llvm.org/docs/AttributeReference.html#enable-if 64 // 65 // Overloads which use this macro should be bracketed by 66 // `#ifdef ABSL_BAD_CALL_IF`. 67 // 68 // Example: 69 // 70 // int isdigit(int c); 71 // #ifdef ABSL_BAD_CALL_IF 72 // int isdigit(int c) 73 // ABSL_BAD_CALL_IF(c <= -1 || c > 255, 74 // "'c' must have the value of an unsigned char or EOF"); 75 // #endif // ABSL_BAD_CALL_IF 76 #if ABSL_HAVE_ATTRIBUTE(enable_if) 77 #define ABSL_BAD_CALL_IF(expr, msg) \ 78 __attribute__((enable_if(expr, "Bad call trap"), unavailable(msg))) 79 #endif 80 81 // ABSL_ASSERT() 82 // 83 // In C++11, `assert` can't be used portably within constexpr functions. 84 // ABSL_ASSERT functions as a runtime assert but works in C++11 constexpr 85 // functions. Example: 86 // 87 // constexpr double Divide(double a, double b) { 88 // return ABSL_ASSERT(b != 0), a / b; 89 // } 90 // 91 // This macro is inspired by 92 // https://akrzemi1.wordpress.com/2017/05/18/asserts-in-constexpr-functions/ 93 #if defined(NDEBUG) 94 #define ABSL_ASSERT(expr) \ 95 (false ? static_cast<void>(expr) : static_cast<void>(0)) 96 #else 97 #define ABSL_ASSERT(expr) \ 98 (ABSL_PREDICT_TRUE((expr)) ? static_cast<void>(0) \ 99 : [] { assert(false && #expr); }()) // NOLINT 100 #endif 101 102 // `ABSL_INTERNAL_HARDENING_ABORT()` controls how `ABSL_HARDENING_ASSERT()` 103 // aborts the program in release mode (when NDEBUG is defined). The 104 // implementation should abort the program as quickly as possible and ideally it 105 // should not be possible to ignore the abort request. 106 #define ABSL_INTERNAL_HARDENING_ABORT() \ 107 do { \ 108 ABSL_INTERNAL_IMMEDIATE_ABORT_IMPL(); \ 109 ABSL_INTERNAL_UNREACHABLE_IMPL(); \ 110 } while (false) 111 112 // ABSL_HARDENING_ASSERT() 113 // 114 // `ABSL_HARDENING_ASSERT()` is like `ABSL_ASSERT()`, but used to implement 115 // runtime assertions that should be enabled in hardened builds even when 116 // `NDEBUG` is defined. 117 // 118 // When `NDEBUG` is not defined, `ABSL_HARDENING_ASSERT()` is identical to 119 // `ABSL_ASSERT()`. 120 // 121 // See `ABSL_OPTION_HARDENED` in `absl/base/options.h` for more information on 122 // hardened mode. 123 #if ABSL_OPTION_HARDENED == 1 && defined(NDEBUG) 124 #define ABSL_HARDENING_ASSERT(expr) \ 125 (ABSL_PREDICT_TRUE((expr)) ? static_cast<void>(0) \ 126 : [] { ABSL_INTERNAL_HARDENING_ABORT(); }()) 127 #else 128 #define ABSL_HARDENING_ASSERT(expr) ABSL_ASSERT(expr) 129 #endif 130 131 #ifdef ABSL_HAVE_EXCEPTIONS 132 #define ABSL_INTERNAL_TRY try 133 #define ABSL_INTERNAL_CATCH_ANY catch (...) 134 #define ABSL_INTERNAL_RETHROW do { throw; } while (false) 135 #else // ABSL_HAVE_EXCEPTIONS 136 #define ABSL_INTERNAL_TRY if (true) 137 #define ABSL_INTERNAL_CATCH_ANY else if (false) 138 #define ABSL_INTERNAL_RETHROW do {} while (false) 139 #endif // ABSL_HAVE_EXCEPTIONS 140 141 // ABSL_DEPRECATE_AND_INLINE() 142 // 143 // Marks a function or type alias as deprecated and tags it to be picked up for 144 // automated refactoring by go/cpp-inliner. It can added to inline function 145 // definitions or type aliases. It should only be used within a header file. It 146 // differs from `ABSL_DEPRECATED` in the following ways: 147 // 148 // 1. New uses of the function or type will be discouraged via Tricorder 149 // warnings. 150 // 2. If enabled via `METADATA`, automated changes will be sent out inlining the 151 // functions's body or replacing the type where it is used. 152 // 153 // For example: 154 // 155 // ABSL_DEPRECATE_AND_INLINE() inline int OldFunc(int x) { 156 // return NewFunc(x, 0); 157 // } 158 // 159 // will mark `OldFunc` as deprecated, and the go/cpp-inliner service will 160 // replace calls to `OldFunc(x)` with calls to `NewFunc(x, 0)`. Once all calls 161 // to `OldFunc` have been replaced, `OldFunc` can be deleted. 162 // 163 // See go/cpp-inliner for more information. 164 // 165 // Note: go/cpp-inliner is Google-internal service for automated refactoring. 166 // While open-source users do not have access to this service, the macro is 167 // provided for compatibility, and so that users receive deprecation warnings. 168 #if ABSL_HAVE_CPP_ATTRIBUTE(deprecated) && \ 169 ABSL_HAVE_CPP_ATTRIBUTE(clang::annotate) 170 #define ABSL_DEPRECATE_AND_INLINE() [[deprecated, clang::annotate("inline-me")]] 171 #elif ABSL_HAVE_CPP_ATTRIBUTE(deprecated) 172 #define ABSL_DEPRECATE_AND_INLINE() [[deprecated]] 173 #else 174 #define ABSL_DEPRECATE_AND_INLINE() 175 #endif 176 177 // Requires the compiler to prove that the size of the given object is at least 178 // the expected amount. 179 #if ABSL_HAVE_ATTRIBUTE(diagnose_if) && ABSL_HAVE_BUILTIN(__builtin_object_size) 180 #define ABSL_INTERNAL_NEED_MIN_SIZE(Obj, N) \ 181 __attribute__((diagnose_if(__builtin_object_size(Obj, 0) < N, \ 182 "object size provably too small " \ 183 "(this would corrupt memory)", \ 184 "error"))) 185 #else 186 #define ABSL_INTERNAL_NEED_MIN_SIZE(Obj, N) 187 #endif 188 189 #endif // ABSL_BASE_MACROS_H_ 190