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