macros.h 8.4 KB

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