1// Copyright 2017 The Abseil Authors.
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7// https://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14//
15// This header file defines macros for declaring attributes for functions,
16// types, and variables.
17//
18// These macros are used within Abseil and allow the compiler to optimize, where
19// applicable, certain function calls.
20//
21// Most macros here are exposing GCC or Clang features, and are stubbed out for
22// other compilers.
23//
24// GCC attributes documentation:
25// https://gcc.gnu.org/onlinedocs/gcc-4.7.0/gcc/Function-Attributes.html
26// https://gcc.gnu.org/onlinedocs/gcc-4.7.0/gcc/Variable-Attributes.html
27// https://gcc.gnu.org/onlinedocs/gcc-4.7.0/gcc/Type-Attributes.html
28//
29// Most attributes in this file are already supported by GCC 4.7. However, some
30// of them are not supported in older version of Clang. Thus, we check
31// `__has_attribute()` first. If the check fails, we check if we are on GCC and
32// assume the attribute exists on GCC (which is verified on GCC 4.7).
33
34#ifndef ABSL_BASE_ATTRIBUTES_H_
35#define ABSL_BASE_ATTRIBUTES_H_
36
37#include "absl/base/config.h"
38
39// ABSL_HAVE_ATTRIBUTE
40//
41// A function-like feature checking macro that is a wrapper around
42// `__has_attribute`, which is defined by GCC 5+ and Clang and evaluates to a
43// nonzero constant integer if the attribute is supported or 0 if not.
44//
45// It evaluates to zero if `__has_attribute` is not defined by the compiler.
46//
47// GCC: https://gcc.gnu.org/gcc-5/changes.html
48// Clang: https://clang.llvm.org/docs/LanguageExtensions.html
49#ifdef __has_attribute
50#define ABSL_HAVE_ATTRIBUTE(x) __has_attribute(x)
51#else
52#define ABSL_HAVE_ATTRIBUTE(x) 0
53#endif
54
55// ABSL_HAVE_CPP_ATTRIBUTE
56//
57// A function-like feature checking macro that accepts C++11 style attributes.
58// It's a wrapper around `__has_cpp_attribute`, defined by ISO C++ SD-6
59// (https://en.cppreference.com/w/cpp/experimental/feature_test). If we don't
60// find `__has_cpp_attribute`, will evaluate to 0.
61#if defined(__cplusplus) && defined(__has_cpp_attribute)
62// NOTE: requiring __cplusplus above should not be necessary, but
63// works around https://bugs.llvm.org/show_bug.cgi?id=23435.
64#define ABSL_HAVE_CPP_ATTRIBUTE(x) __has_cpp_attribute(x)
65#else
66#define ABSL_HAVE_CPP_ATTRIBUTE(x) 0
67#endif
68
69// -----------------------------------------------------------------------------
70// Function Attributes
71// -----------------------------------------------------------------------------
72//
73// GCC: https://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html
74// Clang: https://clang.llvm.org/docs/AttributeReference.html
75
76// ABSL_PRINTF_ATTRIBUTE
77// ABSL_SCANF_ATTRIBUTE
78//
79// Tells the compiler to perform `printf` format string checking if the
80// compiler supports it; see the 'format' attribute in
81// <https://gcc.gnu.org/onlinedocs/gcc-4.7.0/gcc/Function-Attributes.html>.
82//
83// Note: As the GCC manual states, "[s]ince non-static C++ methods
84// have an implicit 'this' argument, the arguments of such methods
85// should be counted from two, not one."
86#if ABSL_HAVE_ATTRIBUTE(format) || (defined(__GNUC__) && !defined(__clang__))
87#define ABSL_PRINTF_ATTRIBUTE(string_index, first_to_check) \
88 __attribute__((__format__(__printf__, string_index, first_to_check)))
89#define ABSL_SCANF_ATTRIBUTE(string_index, first_to_check) \
90 __attribute__((__format__(__scanf__, string_index, first_to_check)))
91#else
92#define ABSL_PRINTF_ATTRIBUTE(string_index, first_to_check)
93#define ABSL_SCANF_ATTRIBUTE(string_index, first_to_check)
94#endif
95
96// ABSL_ATTRIBUTE_ALWAYS_INLINE
97// ABSL_ATTRIBUTE_NOINLINE
98//
99// Forces functions to either inline or not inline. Introduced in gcc 3.1.
100#if ABSL_HAVE_ATTRIBUTE(always_inline) || \
101 (defined(__GNUC__) && !defined(__clang__))
102#define ABSL_ATTRIBUTE_ALWAYS_INLINE __attribute__((always_inline))
103#define ABSL_HAVE_ATTRIBUTE_ALWAYS_INLINE 1
104#else
105#define ABSL_ATTRIBUTE_ALWAYS_INLINE
106#endif
107
108#if ABSL_HAVE_ATTRIBUTE(noinline) || (defined(__GNUC__) && !defined(__clang__))
109#define ABSL_ATTRIBUTE_NOINLINE __attribute__((noinline))
110#define ABSL_HAVE_ATTRIBUTE_NOINLINE 1
111#else
112#define ABSL_ATTRIBUTE_NOINLINE
113#endif
114
115// ABSL_ATTRIBUTE_NO_TAIL_CALL
116//
117// Prevents the compiler from optimizing away stack frames for functions which
118// end in a call to another function.
119#if ABSL_HAVE_ATTRIBUTE(disable_tail_calls)
120#define ABSL_HAVE_ATTRIBUTE_NO_TAIL_CALL 1
121#define ABSL_ATTRIBUTE_NO_TAIL_CALL __attribute__((disable_tail_calls))
122#elif defined(__GNUC__) && !defined(__clang__) && !defined(__e2k__)
123#define ABSL_HAVE_ATTRIBUTE_NO_TAIL_CALL 1
124#define ABSL_ATTRIBUTE_NO_TAIL_CALL \
125 __attribute__((optimize("no-optimize-sibling-calls")))
126#else
127#define ABSL_ATTRIBUTE_NO_TAIL_CALL
128#define ABSL_HAVE_ATTRIBUTE_NO_TAIL_CALL 0
129#endif
130
131// ABSL_ATTRIBUTE_WEAK
132//
133// Tags a function as weak for the purposes of compilation and linking.
134// Weak attributes did not work properly in LLVM's Windows backend before
135// 9.0.0, so disable them there. See https://bugs.llvm.org/show_bug.cgi?id=37598
136// for further information.
137// The MinGW compiler doesn't complain about the weak attribute until the link
138// step, presumably because Windows doesn't use ELF binaries.
139#if (ABSL_HAVE_ATTRIBUTE(weak) || \
140 (defined(__GNUC__) && !defined(__clang__))) && \
141 (!defined(_WIN32) || (defined(__clang__) && __clang_major__ >= 9)) && \
142 !defined(__MINGW32__)
143#undef ABSL_ATTRIBUTE_WEAK
144#define ABSL_ATTRIBUTE_WEAK __attribute__((weak))
145#define ABSL_HAVE_ATTRIBUTE_WEAK 1
146#else
147#define ABSL_ATTRIBUTE_WEAK
148#define ABSL_HAVE_ATTRIBUTE_WEAK 0
149#endif
150
151// ABSL_ATTRIBUTE_NONNULL
152//
153// Tells the compiler either (a) that a particular function parameter
154// should be a non-null pointer, or (b) that all pointer arguments should
155// be non-null.
156//
157// Note: As the GCC manual states, "[s]ince non-static C++ methods
158// have an implicit 'this' argument, the arguments of such methods
159// should be counted from two, not one."
160//
161// Args are indexed starting at 1.
162//
163// For non-static class member functions, the implicit `this` argument
164// is arg 1, and the first explicit argument is arg 2. For static class member
165// functions, there is no implicit `this`, and the first explicit argument is
166// arg 1.
167//
168// Example:
169//
170// /* arg_a cannot be null, but arg_b can */
171// void Function(void* arg_a, void* arg_b) ABSL_ATTRIBUTE_NONNULL(1);
172//
173// class C {
174// /* arg_a cannot be null, but arg_b can */
175// void Method(void* arg_a, void* arg_b) ABSL_ATTRIBUTE_NONNULL(2);
176//
177// /* arg_a cannot be null, but arg_b can */
178// static void StaticMethod(void* arg_a, void* arg_b)
179// ABSL_ATTRIBUTE_NONNULL(1);
180// };
181//
182// If no arguments are provided, then all pointer arguments should be non-null.
183//
184// /* No pointer arguments may be null. */
185// void Function(void* arg_a, void* arg_b, int arg_c) ABSL_ATTRIBUTE_NONNULL();
186//
187// NOTE: The GCC nonnull attribute actually accepts a list of arguments, but
188// ABSL_ATTRIBUTE_NONNULL does not.
189#if ABSL_HAVE_ATTRIBUTE(nonnull) || (defined(__GNUC__) && !defined(__clang__))
190#define ABSL_ATTRIBUTE_NONNULL(arg_index) __attribute__((nonnull(arg_index)))
191#else
192#define ABSL_ATTRIBUTE_NONNULL(...)
193#endif
194
195// ABSL_ATTRIBUTE_NORETURN
196//
197// Tells the compiler that a given function never returns.
198#if ABSL_HAVE_ATTRIBUTE(noreturn) || (defined(__GNUC__) && !defined(__clang__))
199#define ABSL_ATTRIBUTE_NORETURN __attribute__((noreturn))
200#elif defined(_MSC_VER)
201#define ABSL_ATTRIBUTE_NORETURN __declspec(noreturn)
202#else
203#define ABSL_ATTRIBUTE_NORETURN
204#endif
205
206// ABSL_ATTRIBUTE_NO_SANITIZE_ADDRESS
207//
208// Tells the AddressSanitizer (or other memory testing tools) to ignore a given
209// function. Useful for cases when a function reads random locations on stack,
210// calls _exit from a cloned subprocess, deliberately accesses buffer
211// out of bounds or does other scary things with memory.
212// NOTE: GCC supports AddressSanitizer(asan) since 4.8.
213// https://gcc.gnu.org/gcc-4.8/changes.html
214#if defined(ABSL_HAVE_ADDRESS_SANITIZER) && \
215 ABSL_HAVE_ATTRIBUTE(no_sanitize_address)
216#define ABSL_ATTRIBUTE_NO_SANITIZE_ADDRESS __attribute__((no_sanitize_address))
217#elif defined(ABSL_HAVE_ADDRESS_SANITIZER) && defined(_MSC_VER) && \
218 _MSC_VER >= 1928
219// https://docs.microsoft.com/en-us/cpp/cpp/no-sanitize-address
220#define ABSL_ATTRIBUTE_NO_SANITIZE_ADDRESS __declspec(no_sanitize_address)
221#elif defined(ABSL_HAVE_HWADDRESS_SANITIZER) && ABSL_HAVE_ATTRIBUTE(no_sanitize)
222// HWAddressSanitizer is a sanitizer similar to AddressSanitizer, which uses CPU
223// features to detect similar bugs with less CPU and memory overhead.
224// NOTE: GCC supports HWAddressSanitizer(hwasan) since 11.
225// https://gcc.gnu.org/gcc-11/changes.html
226#define ABSL_ATTRIBUTE_NO_SANITIZE_ADDRESS \
227 __attribute__((no_sanitize("hwaddress")))
228#else
229#define ABSL_ATTRIBUTE_NO_SANITIZE_ADDRESS
230#endif
231
232// ABSL_ATTRIBUTE_NO_SANITIZE_MEMORY
233//
234// Tells the MemorySanitizer to relax the handling of a given function. All "Use
235// of uninitialized value" warnings from such functions will be suppressed, and
236// all values loaded from memory will be considered fully initialized. This
237// attribute is similar to the ABSL_ATTRIBUTE_NO_SANITIZE_ADDRESS attribute
238// above, but deals with initialized-ness rather than addressability issues.
239// NOTE: MemorySanitizer(msan) is supported by Clang but not GCC.
240#if ABSL_HAVE_ATTRIBUTE(no_sanitize_memory)
241#define ABSL_ATTRIBUTE_NO_SANITIZE_MEMORY __attribute__((no_sanitize_memory))
242#else
243#define ABSL_ATTRIBUTE_NO_SANITIZE_MEMORY
244#endif
245
246// ABSL_ATTRIBUTE_NO_SANITIZE_THREAD
247//
248// Tells the ThreadSanitizer to not instrument a given function.
249// NOTE: GCC supports ThreadSanitizer(tsan) since 4.8.
250// https://gcc.gnu.org/gcc-4.8/changes.html
251#if ABSL_HAVE_ATTRIBUTE(no_sanitize_thread)
252#define ABSL_ATTRIBUTE_NO_SANITIZE_THREAD __attribute__((no_sanitize_thread))
253#else
254#define ABSL_ATTRIBUTE_NO_SANITIZE_THREAD
255#endif
256
257// ABSL_ATTRIBUTE_NO_SANITIZE_UNDEFINED
258//
259// Tells the UndefinedSanitizer to ignore a given function. Useful for cases
260// where certain behavior (eg. division by zero) is being used intentionally.
261// NOTE: GCC supports UndefinedBehaviorSanitizer(ubsan) since 4.9.
262// https://gcc.gnu.org/gcc-4.9/changes.html
263#if ABSL_HAVE_ATTRIBUTE(no_sanitize_undefined)
264#define ABSL_ATTRIBUTE_NO_SANITIZE_UNDEFINED \
265 __attribute__((no_sanitize_undefined))
266#elif ABSL_HAVE_ATTRIBUTE(no_sanitize)
267#define ABSL_ATTRIBUTE_NO_SANITIZE_UNDEFINED \
268 __attribute__((no_sanitize("undefined")))
269#else
270#define ABSL_ATTRIBUTE_NO_SANITIZE_UNDEFINED
271#endif
272
273// ABSL_ATTRIBUTE_NO_SANITIZE_CFI
274//
275// Tells the ControlFlowIntegrity sanitizer to not instrument a given function.
276// See https://clang.llvm.org/docs/ControlFlowIntegrity.html for details.
277#if ABSL_HAVE_ATTRIBUTE(no_sanitize) && defined(__llvm__)
278#define ABSL_ATTRIBUTE_NO_SANITIZE_CFI __attribute__((no_sanitize("cfi")))
279#else
280#define ABSL_ATTRIBUTE_NO_SANITIZE_CFI
281#endif
282
283// ABSL_ATTRIBUTE_NO_SANITIZE_SAFESTACK
284//
285// Tells the SafeStack to not instrument a given function.
286// See https://clang.llvm.org/docs/SafeStack.html for details.
287#if ABSL_HAVE_ATTRIBUTE(no_sanitize)
288#define ABSL_ATTRIBUTE_NO_SANITIZE_SAFESTACK \
289 __attribute__((no_sanitize("safe-stack")))
290#else
291#define ABSL_ATTRIBUTE_NO_SANITIZE_SAFESTACK
292#endif
293
294// ABSL_ATTRIBUTE_RETURNS_NONNULL
295//
296// Tells the compiler that a particular function never returns a null pointer.
297#if ABSL_HAVE_ATTRIBUTE(returns_nonnull)
298#define ABSL_ATTRIBUTE_RETURNS_NONNULL __attribute__((returns_nonnull))
299#else
300#define ABSL_ATTRIBUTE_RETURNS_NONNULL
301#endif
302
303// ABSL_HAVE_ATTRIBUTE_SECTION
304//
305// Indicates whether labeled sections are supported. Weak symbol support is
306// a prerequisite. Labeled sections are not supported on Darwin/iOS.
307#ifdef ABSL_HAVE_ATTRIBUTE_SECTION
308#error ABSL_HAVE_ATTRIBUTE_SECTION cannot be directly set
309#elif (ABSL_HAVE_ATTRIBUTE(section) || \
310 (defined(__GNUC__) && !defined(__clang__))) && \
311 !defined(__APPLE__) && ABSL_HAVE_ATTRIBUTE_WEAK
312#define ABSL_HAVE_ATTRIBUTE_SECTION 1
313
314// ABSL_ATTRIBUTE_SECTION
315//
316// Tells the compiler/linker to put a given function into a section and define
317// `__start_ ## name` and `__stop_ ## name` symbols to bracket the section.
318// This functionality is supported by GNU linker. Any function annotated with
319// `ABSL_ATTRIBUTE_SECTION` must not be inlined, or it will be placed into
320// whatever section its caller is placed into.
321//
322#ifndef ABSL_ATTRIBUTE_SECTION
323#define ABSL_ATTRIBUTE_SECTION(name) \
324 __attribute__((section(#name))) __attribute__((noinline))
325#endif
326
327// ABSL_ATTRIBUTE_SECTION_VARIABLE
328//
329// Tells the compiler/linker to put a given variable into a section and define
330// `__start_ ## name` and `__stop_ ## name` symbols to bracket the section.
331// This functionality is supported by GNU linker.
332#ifndef ABSL_ATTRIBUTE_SECTION_VARIABLE
333#ifdef _AIX
334// __attribute__((section(#name))) on AIX is achieved by using the `.csect`
335// psudo op which includes an additional integer as part of its syntax indcating
336// alignment. If data fall under different alignments then you might get a
337// compilation error indicating a `Section type conflict`.
338#define ABSL_ATTRIBUTE_SECTION_VARIABLE(name)
339#else
340#define ABSL_ATTRIBUTE_SECTION_VARIABLE(name) __attribute__((section(#name)))
341#endif
342#endif
343
344// ABSL_DECLARE_ATTRIBUTE_SECTION_VARS
345//
346// A weak section declaration to be used as a global declaration
347// for ABSL_ATTRIBUTE_SECTION_START|STOP(name) to compile and link
348// even without functions with ABSL_ATTRIBUTE_SECTION(name).
349// ABSL_DEFINE_ATTRIBUTE_SECTION should be in the exactly one file; it's
350// a no-op on ELF but not on Mach-O.
351//
352#ifndef ABSL_DECLARE_ATTRIBUTE_SECTION_VARS
353#define ABSL_DECLARE_ATTRIBUTE_SECTION_VARS(name) \
354 extern char __start_##name[] ABSL_ATTRIBUTE_WEAK; \
355 extern char __stop_##name[] ABSL_ATTRIBUTE_WEAK
356#endif
357#ifndef ABSL_DEFINE_ATTRIBUTE_SECTION_VARS
358#define ABSL_INIT_ATTRIBUTE_SECTION_VARS(name)
359#define ABSL_DEFINE_ATTRIBUTE_SECTION_VARS(name)
360#endif
361
362// ABSL_ATTRIBUTE_SECTION_START
363//
364// Returns `void*` pointers to start/end of a section of code with
365// functions having ABSL_ATTRIBUTE_SECTION(name).
366// Returns 0 if no such functions exist.
367// One must ABSL_DECLARE_ATTRIBUTE_SECTION_VARS(name) for this to compile and
368// link.
369//
370#define ABSL_ATTRIBUTE_SECTION_START(name) \
371 (reinterpret_cast<void *>(__start_##name))
372#define ABSL_ATTRIBUTE_SECTION_STOP(name) \
373 (reinterpret_cast<void *>(__stop_##name))
374
375#else // !ABSL_HAVE_ATTRIBUTE_SECTION
376
377#define ABSL_HAVE_ATTRIBUTE_SECTION 0
378
379// provide dummy definitions
380#define ABSL_ATTRIBUTE_SECTION(name)
381#define ABSL_ATTRIBUTE_SECTION_VARIABLE(name)
382#define ABSL_INIT_ATTRIBUTE_SECTION_VARS(name)
383#define ABSL_DEFINE_ATTRIBUTE_SECTION_VARS(name)
384#define ABSL_DECLARE_ATTRIBUTE_SECTION_VARS(name)
385#define ABSL_ATTRIBUTE_SECTION_START(name) (reinterpret_cast<void *>(0))
386#define ABSL_ATTRIBUTE_SECTION_STOP(name) (reinterpret_cast<void *>(0))
387
388#endif // ABSL_ATTRIBUTE_SECTION
389
390// ABSL_ATTRIBUTE_STACK_ALIGN_FOR_OLD_LIBC
391//
392// Support for aligning the stack on 32-bit x86.
393#if ABSL_HAVE_ATTRIBUTE(force_align_arg_pointer) || \
394 (defined(__GNUC__) && !defined(__clang__))
395#if defined(__i386__)
396#define ABSL_ATTRIBUTE_STACK_ALIGN_FOR_OLD_LIBC \
397 __attribute__((force_align_arg_pointer))
398#define ABSL_REQUIRE_STACK_ALIGN_TRAMPOLINE (0)
399#elif defined(__x86_64__)
400#define ABSL_REQUIRE_STACK_ALIGN_TRAMPOLINE (1)
401#define ABSL_ATTRIBUTE_STACK_ALIGN_FOR_OLD_LIBC
402#else // !__i386__ && !__x86_64
403#define ABSL_REQUIRE_STACK_ALIGN_TRAMPOLINE (0)
404#define ABSL_ATTRIBUTE_STACK_ALIGN_FOR_OLD_LIBC
405#endif // __i386__
406#else
407#define ABSL_ATTRIBUTE_STACK_ALIGN_FOR_OLD_LIBC
408#define ABSL_REQUIRE_STACK_ALIGN_TRAMPOLINE (0)
409#endif
410
411// ABSL_MUST_USE_RESULT
412//
413// Tells the compiler to warn about unused results.
414//
415// For code or headers that are assured to only build with C++17 and up, prefer
416// just using the standard `[[nodiscard]]` directly over this macro.
417//
418// When annotating a function, it must appear as the first part of the
419// declaration or definition. The compiler will warn if the return value from
420// such a function is unused:
421//
422// ABSL_MUST_USE_RESULT Sprocket* AllocateSprocket();
423// AllocateSprocket(); // Triggers a warning.
424//
425// When annotating a class, it is equivalent to annotating every function which
426// returns an instance.
427//
428// class ABSL_MUST_USE_RESULT Sprocket {};
429// Sprocket(); // Triggers a warning.
430//
431// Sprocket MakeSprocket();
432// MakeSprocket(); // Triggers a warning.
433//
434// Note that references and pointers are not instances:
435//
436// Sprocket* SprocketPointer();
437// SprocketPointer(); // Does *not* trigger a warning.
438//
439// ABSL_MUST_USE_RESULT allows using cast-to-void to suppress the unused result
440// warning. For that, warn_unused_result is used only for clang but not for gcc.
441// https://gcc.gnu.org/bugzilla/show_bug.cgi?id=66425
442//
443// Note: past advice was to place the macro after the argument list.
444//
445// TODO(b/176172494): Use ABSL_HAVE_CPP_ATTRIBUTE(nodiscard) when all code is
446// compliant with the stricter [[nodiscard]].
447#if defined(__clang__) && ABSL_HAVE_ATTRIBUTE(warn_unused_result)
448#define ABSL_MUST_USE_RESULT __attribute__((warn_unused_result))
449#else
450#define ABSL_MUST_USE_RESULT
451#endif
452
453// ABSL_ATTRIBUTE_HOT, ABSL_ATTRIBUTE_COLD
454//
455// Tells GCC that a function is hot or cold. GCC can use this information to
456// improve static analysis, i.e. a conditional branch to a cold function
457// is likely to be not-taken.
458// This annotation is used for function declarations.
459//
460// Example:
461//
462// int foo() ABSL_ATTRIBUTE_HOT;
463#if ABSL_HAVE_ATTRIBUTE(hot) || (defined(__GNUC__) && !defined(__clang__))
464#define ABSL_ATTRIBUTE_HOT __attribute__((hot))
465#else
466#define ABSL_ATTRIBUTE_HOT
467#endif
468
469#if ABSL_HAVE_ATTRIBUTE(cold) || (defined(__GNUC__) && !defined(__clang__))
470#define ABSL_ATTRIBUTE_COLD __attribute__((cold))
471#else
472#define ABSL_ATTRIBUTE_COLD
473#endif
474
475// ABSL_XRAY_ALWAYS_INSTRUMENT, ABSL_XRAY_NEVER_INSTRUMENT, ABSL_XRAY_LOG_ARGS
476//
477// We define the ABSL_XRAY_ALWAYS_INSTRUMENT and ABSL_XRAY_NEVER_INSTRUMENT
478// macro used as an attribute to mark functions that must always or never be
479// instrumented by XRay. Currently, this is only supported in Clang/LLVM.
480//
481// For reference on the LLVM XRay instrumentation, see
482// http://llvm.org/docs/XRay.html.
483//
484// A function with the XRAY_ALWAYS_INSTRUMENT macro attribute in its declaration
485// will always get the XRay instrumentation sleds. These sleds may introduce
486// some binary size and runtime overhead and must be used sparingly.
487//
488// These attributes only take effect when the following conditions are met:
489//
490// * The file/target is built in at least C++11 mode, with a Clang compiler
491// that supports XRay attributes.
492// * The file/target is built with the -fxray-instrument flag set for the
493// Clang/LLVM compiler.
494// * The function is defined in the translation unit (the compiler honors the
495// attribute in either the definition or the declaration, and must match).
496//
497// There are cases when, even when building with XRay instrumentation, users
498// might want to control specifically which functions are instrumented for a
499// particular build using special-case lists provided to the compiler. These
500// special case lists are provided to Clang via the
501// -fxray-always-instrument=... and -fxray-never-instrument=... flags. The
502// attributes in source take precedence over these special-case lists.
503//
504// To disable the XRay attributes at build-time, users may define
505// ABSL_NO_XRAY_ATTRIBUTES. Do NOT define ABSL_NO_XRAY_ATTRIBUTES on specific
506// packages/targets, as this may lead to conflicting definitions of functions at
507// link-time.
508//
509// XRay isn't currently supported on Android:
510// https://github.com/android/ndk/issues/368
511#if ABSL_HAVE_CPP_ATTRIBUTE(clang::xray_always_instrument) && \
512 !defined(ABSL_NO_XRAY_ATTRIBUTES) && !defined(__ANDROID__)
513#define ABSL_XRAY_ALWAYS_INSTRUMENT [[clang::xray_always_instrument]]
514#define ABSL_XRAY_NEVER_INSTRUMENT [[clang::xray_never_instrument]]
515#if ABSL_HAVE_CPP_ATTRIBUTE(clang::xray_log_args)
516#define ABSL_XRAY_LOG_ARGS(N) \
517 [[clang::xray_always_instrument, clang::xray_log_args(N)]]
518#else
519#define ABSL_XRAY_LOG_ARGS(N) [[clang::xray_always_instrument]]
520#endif
521#else
522#define ABSL_XRAY_ALWAYS_INSTRUMENT
523#define ABSL_XRAY_NEVER_INSTRUMENT
524#define ABSL_XRAY_LOG_ARGS(N)
525#endif
526
527// ABSL_ATTRIBUTE_REINITIALIZES
528//
529// Indicates that a member function reinitializes the entire object to a known
530// state, independent of the previous state of the object.
531//
532// The clang-tidy check bugprone-use-after-move allows member functions marked
533// with this attribute to be called on objects that have been moved from;
534// without the attribute, this would result in a use-after-move warning.
535#if ABSL_HAVE_CPP_ATTRIBUTE(clang::reinitializes)
536#define ABSL_ATTRIBUTE_REINITIALIZES [[clang::reinitializes]]
537#else
538#define ABSL_ATTRIBUTE_REINITIALIZES
539#endif
540
541// -----------------------------------------------------------------------------
542// Variable Attributes
543// -----------------------------------------------------------------------------
544
545// ABSL_ATTRIBUTE_UNUSED
546//
547// Prevents the compiler from complaining about variables that appear unused.
548//
549// For code or headers that are assured to only build with C++17 and up, prefer
550// just using the standard '[[maybe_unused]]' directly over this macro.
551//
552// Due to differences in positioning requirements between the old, compiler
553// specific __attribute__ syntax and the now standard [[maybe_unused]], this
554// macro does not attempt to take advantage of '[[maybe_unused]]'.
555#if ABSL_HAVE_ATTRIBUTE(unused) || (defined(__GNUC__) && !defined(__clang__))
556#undef ABSL_ATTRIBUTE_UNUSED
557#define ABSL_ATTRIBUTE_UNUSED __attribute__((__unused__))
558#else
559#define ABSL_ATTRIBUTE_UNUSED
560#endif
561
562// ABSL_ATTRIBUTE_INITIAL_EXEC
563//
564// Tells the compiler to use "initial-exec" mode for a thread-local variable.
565// See http://people.redhat.com/drepper/tls.pdf for the gory details.
566#if ABSL_HAVE_ATTRIBUTE(tls_model) || (defined(__GNUC__) && !defined(__clang__))
567#define ABSL_ATTRIBUTE_INITIAL_EXEC __attribute__((tls_model("initial-exec")))
568#else
569#define ABSL_ATTRIBUTE_INITIAL_EXEC
570#endif
571
572// ABSL_ATTRIBUTE_PACKED
573//
574// Instructs the compiler not to use natural alignment for a tagged data
575// structure, but instead to reduce its alignment to 1.
576//
577// Therefore, DO NOT APPLY THIS ATTRIBUTE TO STRUCTS CONTAINING ATOMICS. Doing
578// so can cause atomic variables to be mis-aligned and silently violate
579// atomicity on x86.
580//
581// This attribute can either be applied to members of a structure or to a
582// structure in its entirety. Applying this attribute (judiciously) to a
583// structure in its entirety to optimize the memory footprint of very
584// commonly-used structs is fine. Do not apply this attribute to a structure in
585// its entirety if the purpose is to control the offsets of the members in the
586// structure. Instead, apply this attribute only to structure members that need
587// it.
588//
589// When applying ABSL_ATTRIBUTE_PACKED only to specific structure members the
590// natural alignment of structure members not annotated is preserved. Aligned
591// member accesses are faster than non-aligned member accesses even if the
592// targeted microprocessor supports non-aligned accesses.
593#if ABSL_HAVE_ATTRIBUTE(packed) || (defined(__GNUC__) && !defined(__clang__))
594#define ABSL_ATTRIBUTE_PACKED __attribute__((__packed__))
595#else
596#define ABSL_ATTRIBUTE_PACKED
597#endif
598
599// ABSL_ATTRIBUTE_FUNC_ALIGN
600//
601// Tells the compiler to align the function start at least to certain
602// alignment boundary
603#if ABSL_HAVE_ATTRIBUTE(aligned) || (defined(__GNUC__) && !defined(__clang__))
604#define ABSL_ATTRIBUTE_FUNC_ALIGN(bytes) __attribute__((aligned(bytes)))
605#else
606#define ABSL_ATTRIBUTE_FUNC_ALIGN(bytes)
607#endif
608
609// ABSL_FALLTHROUGH_INTENDED
610//
611// Annotates implicit fall-through between switch labels, allowing a case to
612// indicate intentional fallthrough and turn off warnings about any lack of a
613// `break` statement. The ABSL_FALLTHROUGH_INTENDED macro should be followed by
614// a semicolon and can be used in most places where `break` can, provided that
615// no statements exist between it and the next switch label.
616//
617// Example:
618//
619// switch (x) {
620// case 40:
621// case 41:
622// if (truth_is_out_there) {
623// ++x;
624// ABSL_FALLTHROUGH_INTENDED; // Use instead of/along with annotations
625// // in comments
626// } else {
627// return x;
628// }
629// case 42:
630// ...
631//
632// Notes: When supported, GCC and Clang can issue a warning on switch labels
633// with unannotated fallthrough using the warning `-Wimplicit-fallthrough`. See
634// clang documentation on language extensions for details:
635// https://clang.llvm.org/docs/AttributeReference.html#fallthrough-clang-fallthrough
636//
637// When used with unsupported compilers, the ABSL_FALLTHROUGH_INTENDED macro has
638// no effect on diagnostics. In any case this macro has no effect on runtime
639// behavior and performance of code.
640
641#ifdef ABSL_FALLTHROUGH_INTENDED
642#error "ABSL_FALLTHROUGH_INTENDED should not be defined."
643#elif ABSL_HAVE_CPP_ATTRIBUTE(fallthrough)
644#define ABSL_FALLTHROUGH_INTENDED [[fallthrough]]
645#elif ABSL_HAVE_CPP_ATTRIBUTE(clang::fallthrough)
646#define ABSL_FALLTHROUGH_INTENDED [[clang::fallthrough]]
647#elif ABSL_HAVE_CPP_ATTRIBUTE(gnu::fallthrough)
648#define ABSL_FALLTHROUGH_INTENDED [[gnu::fallthrough]]
649#else
650#define ABSL_FALLTHROUGH_INTENDED \
651 do { \
652 } while (0)
653#endif
654
655// ABSL_DEPRECATED()
656//
657// Marks a deprecated class, struct, enum, function, method and variable
658// declarations. The macro argument is used as a custom diagnostic message (e.g.
659// suggestion of a better alternative).
660//
661// For code or headers that are assured to only build with C++14 and up, prefer
662// just using the standard `[[deprecated("message")]]` directly over this macro.
663//
664// Examples:
665//
666// class ABSL_DEPRECATED("Use Bar instead") Foo {...};
667//
668// ABSL_DEPRECATED("Use Baz() instead") void Bar() {...}
669//
670// template <typename T>
671// ABSL_DEPRECATED("Use DoThat() instead")
672// void DoThis();
673//
674// enum FooEnum {
675// kBar ABSL_DEPRECATED("Use kBaz instead"),
676// };
677//
678// Every usage of a deprecated entity will trigger a warning when compiled with
679// GCC/Clang's `-Wdeprecated-declarations` option. Google's production toolchain
680// turns this warning off by default, instead relying on clang-tidy to report
681// new uses of deprecated code.
682#if ABSL_HAVE_ATTRIBUTE(deprecated)
683#define ABSL_DEPRECATED(message) __attribute__((deprecated(message)))
684#else
685#define ABSL_DEPRECATED(message)
686#endif
687
688// When deprecating Abseil code, it is sometimes necessary to turn off the
689// warning within Abseil, until the deprecated code is actually removed. The
690// deprecated code can be surrounded with these directives to achieve that
691// result.
692//
693// class ABSL_DEPRECATED("Use Bar instead") Foo;
694//
695// ABSL_INTERNAL_DISABLE_DEPRECATED_DECLARATION_WARNING
696// Baz ComputeBazFromFoo(Foo f);
697// ABSL_INTERNAL_RESTORE_DEPRECATED_DECLARATION_WARNING
698#if defined(__GNUC__) || defined(__clang__)
699// Clang also supports these GCC pragmas.
700#define ABSL_INTERNAL_DISABLE_DEPRECATED_DECLARATION_WARNING \
701 _Pragma("GCC diagnostic push") \
702 _Pragma("GCC diagnostic ignored \"-Wdeprecated-declarations\"")
703#define ABSL_INTERNAL_RESTORE_DEPRECATED_DECLARATION_WARNING \
704 _Pragma("GCC diagnostic pop")
705#else
706#define ABSL_INTERNAL_DISABLE_DEPRECATED_DECLARATION_WARNING
707#define ABSL_INTERNAL_RESTORE_DEPRECATED_DECLARATION_WARNING
708#endif // defined(__GNUC__) || defined(__clang__)
709
710// ABSL_CONST_INIT
711//
712// A variable declaration annotated with the `ABSL_CONST_INIT` attribute will
713// not compile (on supported platforms) unless the variable has a constant
714// initializer. This is useful for variables with static and thread storage
715// duration, because it guarantees that they will not suffer from the so-called
716// "static init order fiasco".
717//
718// This attribute must be placed on the initializing declaration of the
719// variable. Some compilers will give a -Wmissing-constinit warning when this
720// attribute is placed on some other declaration but missing from the
721// initializing declaration.
722//
723// In some cases (notably with thread_local variables), `ABSL_CONST_INIT` can
724// also be used in a non-initializing declaration to tell the compiler that a
725// variable is already initialized, reducing overhead that would otherwise be
726// incurred by a hidden guard variable. Thus annotating all declarations with
727// this attribute is recommended to potentially enhance optimization.
728//
729// Example:
730//
731// class MyClass {
732// public:
733// ABSL_CONST_INIT static MyType my_var;
734// };
735//
736// ABSL_CONST_INIT MyType MyClass::my_var = MakeMyType(...);
737//
738// For code or headers that are assured to only build with C++20 and up, prefer
739// just using the standard `constinit` keyword directly over this macro.
740//
741// Note that this attribute is redundant if the variable is declared constexpr.
742#if defined(__cpp_constinit) && __cpp_constinit >= 201907L
743#define ABSL_CONST_INIT constinit
744#elif ABSL_HAVE_CPP_ATTRIBUTE(clang::require_constant_initialization)
745#define ABSL_CONST_INIT [[clang::require_constant_initialization]]
746#else
747#define ABSL_CONST_INIT
748#endif
749
750// ABSL_ATTRIBUTE_PURE_FUNCTION
751//
752// ABSL_ATTRIBUTE_PURE_FUNCTION is used to annotate declarations of "pure"
753// functions. A function is pure if its return value is only a function of its
754// arguments. The pure attribute prohibits a function from modifying the state
755// of the program that is observable by means other than inspecting the
756// function's return value. Declaring such functions with the pure attribute
757// allows the compiler to avoid emitting some calls in repeated invocations of
758// the function with the same argument values.
759//
760// Example:
761//
762// ABSL_ATTRIBUTE_PURE_FUNCTION std::string FormatTime(Time t);
763#if ABSL_HAVE_CPP_ATTRIBUTE(gnu::pure)
764#define ABSL_ATTRIBUTE_PURE_FUNCTION [[gnu::pure]]
765#elif ABSL_HAVE_ATTRIBUTE(pure)
766#define ABSL_ATTRIBUTE_PURE_FUNCTION __attribute__((pure))
767#else
768// If the attribute isn't defined, we'll fallback to ABSL_MUST_USE_RESULT since
769// pure functions are useless if its return is ignored.
770#define ABSL_ATTRIBUTE_PURE_FUNCTION ABSL_MUST_USE_RESULT
771#endif
772
773// ABSL_ATTRIBUTE_CONST_FUNCTION
774//
775// ABSL_ATTRIBUTE_CONST_FUNCTION is used to annotate declarations of "const"
776// functions. A const function is similar to a pure function, with one
777// exception: Pure functions may return value that depend on a non-volatile
778// object that isn't provided as a function argument, while the const function
779// is guaranteed to return the same result given the same arguments.
780//
781// Example:
782//
783// ABSL_ATTRIBUTE_CONST_FUNCTION int64_t ToInt64Milliseconds(Duration d);
784#if defined(_MSC_VER) && !defined(__clang__)
785// Put the MSVC case first since MSVC seems to parse const as a C++ keyword.
786#define ABSL_ATTRIBUTE_CONST_FUNCTION ABSL_ATTRIBUTE_PURE_FUNCTION
787#elif ABSL_HAVE_CPP_ATTRIBUTE(gnu::const)
788#define ABSL_ATTRIBUTE_CONST_FUNCTION [[gnu::const]]
789#elif ABSL_HAVE_ATTRIBUTE(const)
790#define ABSL_ATTRIBUTE_CONST_FUNCTION __attribute__((const))
791#else
792// Since const functions are more restrictive pure function, we'll fallback to a
793// pure function if the const attribute is not handled.
794#define ABSL_ATTRIBUTE_CONST_FUNCTION ABSL_ATTRIBUTE_PURE_FUNCTION
795#endif
796
797// ABSL_ATTRIBUTE_LIFETIME_BOUND indicates that a resource owned by a function
798// parameter or implicit object parameter is retained by the return value of the
799// annotated function (or, for a parameter of a constructor, in the value of the
800// constructed object). This attribute causes warnings to be produced if a
801// temporary object does not live long enough.
802//
803// When applied to a reference parameter, the referenced object is assumed to be
804// retained by the return value of the function. When applied to a non-reference
805// parameter (for example, a pointer or a class type), all temporaries
806// referenced by the parameter are assumed to be retained by the return value of
807// the function.
808//
809// See also the upstream documentation:
810// https://clang.llvm.org/docs/AttributeReference.html#lifetimebound
811#if ABSL_HAVE_CPP_ATTRIBUTE(clang::lifetimebound)
812#define ABSL_ATTRIBUTE_LIFETIME_BOUND [[clang::lifetimebound]]
813#elif ABSL_HAVE_ATTRIBUTE(lifetimebound)
814#define ABSL_ATTRIBUTE_LIFETIME_BOUND __attribute__((lifetimebound))
815#else
816#define ABSL_ATTRIBUTE_LIFETIME_BOUND
817#endif
818
819// ABSL_ATTRIBUTE_TRIVIAL_ABI
820// Indicates that a type is "trivially relocatable" -- meaning it can be
821// relocated without invoking the constructor/destructor, using a form of move
822// elision.
823//
824// From a memory safety point of view, putting aside destructor ordering, it's
825// safe to apply ABSL_ATTRIBUTE_TRIVIAL_ABI if an object's location
826// can change over the course of its lifetime: if a constructor can be run one
827// place, and then the object magically teleports to another place where some
828// methods are run, and then the object teleports to yet another place where it
829// is destroyed. This is notably not true for self-referential types, where the
830// move-constructor must keep the self-reference up to date. If the type changed
831// location without invoking the move constructor, it would have a dangling
832// self-reference.
833//
834// The use of this teleporting machinery means that the number of paired
835// move/destroy operations can change, and so it is a bad idea to apply this to
836// a type meant to count the number of moves.
837//
838// Warning: applying this can, rarely, break callers. Objects passed by value
839// will be destroyed at the end of the call, instead of the end of the
840// full-expression containing the call. In addition, it changes the ABI
841// of functions accepting this type by value (e.g. to pass in registers).
842//
843// See also the upstream documentation:
844// https://clang.llvm.org/docs/AttributeReference.html#trivial-abi
845//
846// b/321691395 - This is currently disabled in open-source builds since
847// compiler support differs. If system libraries compiled with GCC are mixed
848// with libraries compiled with Clang, types will have different ideas about
849// their ABI, leading to hard to debug crashes.
850#define ABSL_ATTRIBUTE_TRIVIAL_ABI
851
852// ABSL_ATTRIBUTE_NO_UNIQUE_ADDRESS
853//
854// Indicates a data member can be optimized to occupy no space (if it is empty)
855// and/or its tail padding can be used for other members.
856//
857// For code that is assured to only build with C++20 or later, prefer using
858// the standard attribute `[[no_unique_address]]` directly instead of this
859// macro.
860//
861// https://devblogs.microsoft.com/cppblog/msvc-cpp20-and-the-std-cpp20-switch/#c20-no_unique_address
862// Current versions of MSVC have disabled `[[no_unique_address]]` since it
863// breaks ABI compatibility, but offers `[[msvc::no_unique_address]]` for
864// situations when it can be assured that it is desired. Since Abseil does not
865// claim ABI compatibility in mixed builds, we can offer it unconditionally.
866#if defined(_MSC_VER) && _MSC_VER >= 1929
867#define ABSL_ATTRIBUTE_NO_UNIQUE_ADDRESS [[msvc::no_unique_address]]
868#elif ABSL_HAVE_CPP_ATTRIBUTE(no_unique_address)
869#define ABSL_ATTRIBUTE_NO_UNIQUE_ADDRESS [[no_unique_address]]
870#else
871#define ABSL_ATTRIBUTE_NO_UNIQUE_ADDRESS
872#endif
873
874#endif // ABSL_BASE_ATTRIBUTES_H_
875