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// This file is used for both C and C++!
22//
23// Most macros here are exposing GCC or Clang features, and are stubbed out for
24// other compilers.
25//
26// GCC attributes documentation:
27// https://gcc.gnu.org/onlinedocs/gcc-4.7.0/gcc/Function-Attributes.html
28// https://gcc.gnu.org/onlinedocs/gcc-4.7.0/gcc/Variable-Attributes.html
29// https://gcc.gnu.org/onlinedocs/gcc-4.7.0/gcc/Type-Attributes.html
30//
31// Most attributes in this file are already supported by GCC 4.7. However, some
32// of them are not supported in older version of Clang. Thus, we check
33// `__has_attribute()` first. If the check fails, we check if we are on GCC and
34// assume the attribute exists on GCC (which is verified on GCC 4.7).
35//
36// -----------------------------------------------------------------------------
37// Sanitizer Attributes
38// -----------------------------------------------------------------------------
39//
40// Sanitizer-related attributes are not "defined" in this file (and indeed
41// are not defined as such in any file). To utilize the following
42// sanitizer-related attributes within your builds, define the following macros
43// within your build using a `-D` flag, along with the given value for
44// `-fsanitize`:
45//
46// * `ADDRESS_SANITIZER` + `-fsanitize=address` (Clang, GCC 4.8)
47// * `MEMORY_SANITIZER` + `-fsanitize=memory` (Clang-only)
48// * `THREAD_SANITIZER + `-fsanitize=thread` (Clang, GCC 4.8+)
49// * `UNDEFINED_BEHAVIOR_SANITIZER` + `-fsanitize=undefined` (Clang, GCC 4.9+)
50// * `CONTROL_FLOW_INTEGRITY` + -fsanitize=cfi (Clang-only)
51//
52// Example:
53//
54// // Enable branches in the Abseil code that are tagged for ASan:
55// $ bazel build --copt=-DADDRESS_SANITIZER --copt=-fsanitize=address
56// --linkopt=-fsanitize=address *target*
57//
58// Since these macro names are only supported by GCC and Clang, we only check
59// for `__GNUC__` (GCC or Clang) and the above macros.
60#ifndef ABSL_BASE_ATTRIBUTES_H_
61#define ABSL_BASE_ATTRIBUTES_H_
62
63// ABSL_HAVE_ATTRIBUTE
64//
65// A function-like feature checking macro that is a wrapper around
66// `__has_attribute`, which is defined by GCC 5+ and Clang and evaluates to a
67// nonzero constant integer if the attribute is supported or 0 if not.
68//
69// It evaluates to zero if `__has_attribute` is not defined by the compiler.
70//
71// GCC: https://gcc.gnu.org/gcc-5/changes.html
72// Clang: https://clang.llvm.org/docs/LanguageExtensions.html
73#ifdef __has_attribute
74#define ABSL_HAVE_ATTRIBUTE(x) __has_attribute(x)
75#else
76#define ABSL_HAVE_ATTRIBUTE(x) 0
77#endif
78
79// ABSL_HAVE_CPP_ATTRIBUTE
80//
81// A function-like feature checking macro that accepts C++11 style attributes.
82// It's a wrapper around `__has_cpp_attribute`, defined by ISO C++ SD-6
83// (https://en.cppreference.com/w/cpp/experimental/feature_test). If we don't
84// find `__has_cpp_attribute`, will evaluate to 0.
85#if defined(__cplusplus) && defined(__has_cpp_attribute)
86// NOTE: requiring __cplusplus above should not be necessary, but
87// works around https://bugs.llvm.org/show_bug.cgi?id=23435.
88#define ABSL_HAVE_CPP_ATTRIBUTE(x) __has_cpp_attribute(x)
89#else
90#define ABSL_HAVE_CPP_ATTRIBUTE(x) 0
91#endif
92
93// -----------------------------------------------------------------------------
94// Function Attributes
95// -----------------------------------------------------------------------------
96//
97// GCC: https://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html
98// Clang: https://clang.llvm.org/docs/AttributeReference.html
99
100// ABSL_PRINTF_ATTRIBUTE
101// ABSL_SCANF_ATTRIBUTE
102//
103// Tells the compiler to perform `printf` format string checking if the
104// compiler supports it; see the 'format' attribute in
105// <https://gcc.gnu.org/onlinedocs/gcc-4.7.0/gcc/Function-Attributes.html>.
106//
107// Note: As the GCC manual states, "[s]ince non-static C++ methods
108// have an implicit 'this' argument, the arguments of such methods
109// should be counted from two, not one."
110#if ABSL_HAVE_ATTRIBUTE(format) || (defined(__GNUC__) && !defined(__clang__))
111#define ABSL_PRINTF_ATTRIBUTE(string_index, first_to_check) \
112 __attribute__((__format__(__printf__, string_index, first_to_check)))
113#define ABSL_SCANF_ATTRIBUTE(string_index, first_to_check) \
114 __attribute__((__format__(__scanf__, string_index, first_to_check)))
115#else
116#define ABSL_PRINTF_ATTRIBUTE(string_index, first_to_check)
117#define ABSL_SCANF_ATTRIBUTE(string_index, first_to_check)
118#endif
119
120// ABSL_ATTRIBUTE_ALWAYS_INLINE
121// ABSL_ATTRIBUTE_NOINLINE
122//
123// Forces functions to either inline or not inline. Introduced in gcc 3.1.
124#if ABSL_HAVE_ATTRIBUTE(always_inline) || \
125 (defined(__GNUC__) && !defined(__clang__))
126#define ABSL_ATTRIBUTE_ALWAYS_INLINE __attribute__((always_inline))
127#define ABSL_HAVE_ATTRIBUTE_ALWAYS_INLINE 1
128#else
129#define ABSL_ATTRIBUTE_ALWAYS_INLINE
130#endif
131
132#if ABSL_HAVE_ATTRIBUTE(noinline) || (defined(__GNUC__) && !defined(__clang__))
133#define ABSL_ATTRIBUTE_NOINLINE __attribute__((noinline))
134#define ABSL_HAVE_ATTRIBUTE_NOINLINE 1
135#else
136#define ABSL_ATTRIBUTE_NOINLINE
137#endif
138
139// ABSL_ATTRIBUTE_NO_TAIL_CALL
140//
141// Prevents the compiler from optimizing away stack frames for functions which
142// end in a call to another function.
143#if ABSL_HAVE_ATTRIBUTE(disable_tail_calls)
144#define ABSL_HAVE_ATTRIBUTE_NO_TAIL_CALL 1
145#define ABSL_ATTRIBUTE_NO_TAIL_CALL __attribute__((disable_tail_calls))
146#elif defined(__GNUC__) && !defined(__clang__)
147#define ABSL_HAVE_ATTRIBUTE_NO_TAIL_CALL 1
148#define ABSL_ATTRIBUTE_NO_TAIL_CALL \
149 __attribute__((optimize("no-optimize-sibling-calls")))
150#else
151#define ABSL_ATTRIBUTE_NO_TAIL_CALL
152#define ABSL_HAVE_ATTRIBUTE_NO_TAIL_CALL 0
153#endif
154
155// ABSL_ATTRIBUTE_WEAK
156//
157// Tags a function as weak for the purposes of compilation and linking.
158// Weak attributes currently do not work properly in LLVM's Windows backend,
159// so disable them there. See https://bugs.llvm.org/show_bug.cgi?id=37598
160// for futher information.
161#if (ABSL_HAVE_ATTRIBUTE(weak) || \
162 (defined(__GNUC__) && !defined(__clang__))) && \
163 !(defined(__llvm__) && defined(_WIN32))
164#undef ABSL_ATTRIBUTE_WEAK
165#define ABSL_ATTRIBUTE_WEAK __attribute__((weak))
166#define ABSL_HAVE_ATTRIBUTE_WEAK 1
167#else
168#define ABSL_ATTRIBUTE_WEAK
169#define ABSL_HAVE_ATTRIBUTE_WEAK 0
170#endif
171
172// ABSL_ATTRIBUTE_NONNULL
173//
174// Tells the compiler either (a) that a particular function parameter
175// should be a non-null pointer, or (b) that all pointer arguments should
176// be non-null.
177//
178// Note: As the GCC manual states, "[s]ince non-static C++ methods
179// have an implicit 'this' argument, the arguments of such methods
180// should be counted from two, not one."
181//
182// Args are indexed starting at 1.
183//
184// For non-static class member functions, the implicit `this` argument
185// is arg 1, and the first explicit argument is arg 2. For static class member
186// functions, there is no implicit `this`, and the first explicit argument is
187// arg 1.
188//
189// Example:
190//
191// /* arg_a cannot be null, but arg_b can */
192// void Function(void* arg_a, void* arg_b) ABSL_ATTRIBUTE_NONNULL(1);
193//
194// class C {
195// /* arg_a cannot be null, but arg_b can */
196// void Method(void* arg_a, void* arg_b) ABSL_ATTRIBUTE_NONNULL(2);
197//
198// /* arg_a cannot be null, but arg_b can */
199// static void StaticMethod(void* arg_a, void* arg_b)
200// ABSL_ATTRIBUTE_NONNULL(1);
201// };
202//
203// If no arguments are provided, then all pointer arguments should be non-null.
204//
205// /* No pointer arguments may be null. */
206// void Function(void* arg_a, void* arg_b, int arg_c) ABSL_ATTRIBUTE_NONNULL();
207//
208// NOTE: The GCC nonnull attribute actually accepts a list of arguments, but
209// ABSL_ATTRIBUTE_NONNULL does not.
210#if ABSL_HAVE_ATTRIBUTE(nonnull) || (defined(__GNUC__) && !defined(__clang__))
211#define ABSL_ATTRIBUTE_NONNULL(arg_index) __attribute__((nonnull(arg_index)))
212#else
213#define ABSL_ATTRIBUTE_NONNULL(...)
214#endif
215
216// ABSL_ATTRIBUTE_NORETURN
217//
218// Tells the compiler that a given function never returns.
219#if ABSL_HAVE_ATTRIBUTE(noreturn) || (defined(__GNUC__) && !defined(__clang__))
220#define ABSL_ATTRIBUTE_NORETURN __attribute__((noreturn))
221#elif defined(_MSC_VER)
222#define ABSL_ATTRIBUTE_NORETURN __declspec(noreturn)
223#else
224#define ABSL_ATTRIBUTE_NORETURN
225#endif
226
227// ABSL_ATTRIBUTE_NO_SANITIZE_ADDRESS
228//
229// Tells the AddressSanitizer (or other memory testing tools) to ignore a given
230// function. Useful for cases when a function reads random locations on stack,
231// calls _exit from a cloned subprocess, deliberately accesses buffer
232// out of bounds or does other scary things with memory.
233// NOTE: GCC supports AddressSanitizer(asan) since 4.8.
234// https://gcc.gnu.org/gcc-4.8/changes.html
235#if defined(__GNUC__)
236#define ABSL_ATTRIBUTE_NO_SANITIZE_ADDRESS __attribute__((no_sanitize_address))
237#else
238#define ABSL_ATTRIBUTE_NO_SANITIZE_ADDRESS
239#endif
240
241// ABSL_ATTRIBUTE_NO_SANITIZE_MEMORY
242//
243// Tells the MemorySanitizer to relax the handling of a given function. All
244// "Use of uninitialized value" warnings from such functions will be suppressed,
245// and all values loaded from memory will be considered fully initialized.
246// This attribute is similar to the ADDRESS_SANITIZER attribute above, but deals
247// with initialized-ness rather than addressability issues.
248// NOTE: MemorySanitizer(msan) is supported by Clang but not GCC.
249#if defined(__clang__)
250#define ABSL_ATTRIBUTE_NO_SANITIZE_MEMORY __attribute__((no_sanitize_memory))
251#else
252#define ABSL_ATTRIBUTE_NO_SANITIZE_MEMORY
253#endif
254
255// ABSL_ATTRIBUTE_NO_SANITIZE_THREAD
256//
257// Tells the ThreadSanitizer to not instrument a given function.
258// NOTE: GCC supports ThreadSanitizer(tsan) since 4.8.
259// https://gcc.gnu.org/gcc-4.8/changes.html
260#if defined(__GNUC__)
261#define ABSL_ATTRIBUTE_NO_SANITIZE_THREAD __attribute__((no_sanitize_thread))
262#else
263#define ABSL_ATTRIBUTE_NO_SANITIZE_THREAD
264#endif
265
266// ABSL_ATTRIBUTE_NO_SANITIZE_UNDEFINED
267//
268// Tells the UndefinedSanitizer to ignore a given function. Useful for cases
269// where certain behavior (eg. division by zero) is being used intentionally.
270// NOTE: GCC supports UndefinedBehaviorSanitizer(ubsan) since 4.9.
271// https://gcc.gnu.org/gcc-4.9/changes.html
272#if defined(__GNUC__) && \
273 (defined(UNDEFINED_BEHAVIOR_SANITIZER) || defined(ADDRESS_SANITIZER))
274#define ABSL_ATTRIBUTE_NO_SANITIZE_UNDEFINED \
275 __attribute__((no_sanitize("undefined")))
276#else
277#define ABSL_ATTRIBUTE_NO_SANITIZE_UNDEFINED
278#endif
279
280// ABSL_ATTRIBUTE_NO_SANITIZE_CFI
281//
282// Tells the ControlFlowIntegrity sanitizer to not instrument a given function.
283// See https://clang.llvm.org/docs/ControlFlowIntegrity.html for details.
284#if defined(__GNUC__) && defined(CONTROL_FLOW_INTEGRITY)
285#define ABSL_ATTRIBUTE_NO_SANITIZE_CFI __attribute__((no_sanitize("cfi")))
286#else
287#define ABSL_ATTRIBUTE_NO_SANITIZE_CFI
288#endif
289
290// ABSL_ATTRIBUTE_NO_SANITIZE_SAFESTACK
291//
292// Tells the SafeStack to not instrument a given function.
293// See https://clang.llvm.org/docs/SafeStack.html for details.
294#if defined(__GNUC__) && defined(SAFESTACK_SANITIZER)
295#define ABSL_ATTRIBUTE_NO_SANITIZE_SAFESTACK \
296 __attribute__((no_sanitize("safe-stack")))
297#else
298#define ABSL_ATTRIBUTE_NO_SANITIZE_SAFESTACK
299#endif
300
301// ABSL_ATTRIBUTE_RETURNS_NONNULL
302//
303// Tells the compiler that a particular function never returns a null pointer.
304#if ABSL_HAVE_ATTRIBUTE(returns_nonnull) || \
305 (defined(__GNUC__) && \
306 (__GNUC__ > 5 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 9)) && \
307 !defined(__clang__))
308#define ABSL_ATTRIBUTE_RETURNS_NONNULL __attribute__((returns_nonnull))
309#else
310#define ABSL_ATTRIBUTE_RETURNS_NONNULL
311#endif
312
313// ABSL_HAVE_ATTRIBUTE_SECTION
314//
315// Indicates whether labeled sections are supported. Weak symbol support is
316// a prerequisite. Labeled sections are not supported on Darwin/iOS.
317#ifdef ABSL_HAVE_ATTRIBUTE_SECTION
318#error ABSL_HAVE_ATTRIBUTE_SECTION cannot be directly set
319#elif (ABSL_HAVE_ATTRIBUTE(section) || \
320 (defined(__GNUC__) && !defined(__clang__))) && \
321 !defined(__APPLE__) && ABSL_HAVE_ATTRIBUTE_WEAK
322#define ABSL_HAVE_ATTRIBUTE_SECTION 1
323
324// ABSL_ATTRIBUTE_SECTION
325//
326// Tells the compiler/linker to put a given function into a section and define
327// `__start_ ## name` and `__stop_ ## name` symbols to bracket the section.
328// This functionality is supported by GNU linker. Any function annotated with
329// `ABSL_ATTRIBUTE_SECTION` must not be inlined, or it will be placed into
330// whatever section its caller is placed into.
331//
332#ifndef ABSL_ATTRIBUTE_SECTION
333#define ABSL_ATTRIBUTE_SECTION(name) \
334 __attribute__((section(#name))) __attribute__((noinline))
335#endif
336
337
338// ABSL_ATTRIBUTE_SECTION_VARIABLE
339//
340// Tells the compiler/linker to put a given variable into a section and define
341// `__start_ ## name` and `__stop_ ## name` symbols to bracket the section.
342// This functionality is supported by GNU linker.
343#ifndef ABSL_ATTRIBUTE_SECTION_VARIABLE
344#define ABSL_ATTRIBUTE_SECTION_VARIABLE(name) __attribute__((section(#name)))
345#endif
346
347// ABSL_DECLARE_ATTRIBUTE_SECTION_VARS
348//
349// A weak section declaration to be used as a global declaration
350// for ABSL_ATTRIBUTE_SECTION_START|STOP(name) to compile and link
351// even without functions with ABSL_ATTRIBUTE_SECTION(name).
352// ABSL_DEFINE_ATTRIBUTE_SECTION should be in the exactly one file; it's
353// a no-op on ELF but not on Mach-O.
354//
355#ifndef ABSL_DECLARE_ATTRIBUTE_SECTION_VARS
356#define ABSL_DECLARE_ATTRIBUTE_SECTION_VARS(name) \
357 extern char __start_##name[] ABSL_ATTRIBUTE_WEAK; \
358 extern char __stop_##name[] ABSL_ATTRIBUTE_WEAK
359#endif
360#ifndef ABSL_DEFINE_ATTRIBUTE_SECTION_VARS
361#define ABSL_INIT_ATTRIBUTE_SECTION_VARS(name)
362#define ABSL_DEFINE_ATTRIBUTE_SECTION_VARS(name)
363#endif
364
365// ABSL_ATTRIBUTE_SECTION_START
366//
367// Returns `void*` pointers to start/end of a section of code with
368// functions having ABSL_ATTRIBUTE_SECTION(name).
369// Returns 0 if no such functions exist.
370// One must ABSL_DECLARE_ATTRIBUTE_SECTION_VARS(name) for this to compile and
371// link.
372//
373#define ABSL_ATTRIBUTE_SECTION_START(name) \
374 (reinterpret_cast<void *>(__start_##name))
375#define ABSL_ATTRIBUTE_SECTION_STOP(name) \
376 (reinterpret_cast<void *>(__stop_##name))
377
378#else // !ABSL_HAVE_ATTRIBUTE_SECTION
379
380#define ABSL_HAVE_ATTRIBUTE_SECTION 0
381
382// provide dummy definitions
383#define ABSL_ATTRIBUTE_SECTION(name)
384#define ABSL_ATTRIBUTE_SECTION_VARIABLE(name)
385#define ABSL_INIT_ATTRIBUTE_SECTION_VARS(name)
386#define ABSL_DEFINE_ATTRIBUTE_SECTION_VARS(name)
387#define ABSL_DECLARE_ATTRIBUTE_SECTION_VARS(name)
388#define ABSL_ATTRIBUTE_SECTION_START(name) (reinterpret_cast<void *>(0))
389#define ABSL_ATTRIBUTE_SECTION_STOP(name) (reinterpret_cast<void *>(0))
390
391#endif // ABSL_ATTRIBUTE_SECTION
392
393// ABSL_ATTRIBUTE_STACK_ALIGN_FOR_OLD_LIBC
394//
395// Support for aligning the stack on 32-bit x86.
396#if ABSL_HAVE_ATTRIBUTE(force_align_arg_pointer) || \
397 (defined(__GNUC__) && !defined(__clang__))
398#if defined(__i386__)
399#define ABSL_ATTRIBUTE_STACK_ALIGN_FOR_OLD_LIBC \
400 __attribute__((force_align_arg_pointer))
401#define ABSL_REQUIRE_STACK_ALIGN_TRAMPOLINE (0)
402#elif defined(__x86_64__)
403#define ABSL_REQUIRE_STACK_ALIGN_TRAMPOLINE (1)
404#define ABSL_ATTRIBUTE_STACK_ALIGN_FOR_OLD_LIBC
405#else // !__i386__ && !__x86_64
406#define ABSL_REQUIRE_STACK_ALIGN_TRAMPOLINE (0)
407#define ABSL_ATTRIBUTE_STACK_ALIGN_FOR_OLD_LIBC
408#endif // __i386__
409#else
410#define ABSL_ATTRIBUTE_STACK_ALIGN_FOR_OLD_LIBC
411#define ABSL_REQUIRE_STACK_ALIGN_TRAMPOLINE (0)
412#endif
413
414// ABSL_MUST_USE_RESULT
415//
416// Tells the compiler to warn about unused results.
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#if ABSL_HAVE_ATTRIBUTE(nodiscard)
445#define ABSL_MUST_USE_RESULT [[nodiscard]]
446#elif defined(__clang__) && ABSL_HAVE_ATTRIBUTE(warn_unused_result)
447#define ABSL_MUST_USE_RESULT __attribute__((warn_unused_result))
448#else
449#define ABSL_MUST_USE_RESULT
450#endif
451
452// ABSL_ATTRIBUTE_HOT, ABSL_ATTRIBUTE_COLD
453//
454// Tells GCC that a function is hot or cold. GCC can use this information to
455// improve static analysis, i.e. a conditional branch to a cold function
456// is likely to be not-taken.
457// This annotation is used for function declarations.
458//
459// Example:
460//
461// int foo() ABSL_ATTRIBUTE_HOT;
462#if ABSL_HAVE_ATTRIBUTE(hot) || (defined(__GNUC__) && !defined(__clang__))
463#define ABSL_ATTRIBUTE_HOT __attribute__((hot))
464#else
465#define ABSL_ATTRIBUTE_HOT
466#endif
467
468#if ABSL_HAVE_ATTRIBUTE(cold) || (defined(__GNUC__) && !defined(__clang__))
469#define ABSL_ATTRIBUTE_COLD __attribute__((cold))
470#else
471#define ABSL_ATTRIBUTE_COLD
472#endif
473
474// ABSL_XRAY_ALWAYS_INSTRUMENT, ABSL_XRAY_NEVER_INSTRUMENT, ABSL_XRAY_LOG_ARGS
475//
476// We define the ABSL_XRAY_ALWAYS_INSTRUMENT and ABSL_XRAY_NEVER_INSTRUMENT
477// macro used as an attribute to mark functions that must always or never be
478// instrumented by XRay. Currently, this is only supported in Clang/LLVM.
479//
480// For reference on the LLVM XRay instrumentation, see
481// http://llvm.org/docs/XRay.html.
482//
483// A function with the XRAY_ALWAYS_INSTRUMENT macro attribute in its declaration
484// will always get the XRay instrumentation sleds. These sleds may introduce
485// some binary size and runtime overhead and must be used sparingly.
486//
487// These attributes only take effect when the following conditions are met:
488//
489// * The file/target is built in at least C++11 mode, with a Clang compiler
490// that supports XRay attributes.
491// * The file/target is built with the -fxray-instrument flag set for the
492// Clang/LLVM compiler.
493// * The function is defined in the translation unit (the compiler honors the
494// attribute in either the definition or the declaration, and must match).
495//
496// There are cases when, even when building with XRay instrumentation, users
497// might want to control specifically which functions are instrumented for a
498// particular build using special-case lists provided to the compiler. These
499// special case lists are provided to Clang via the
500// -fxray-always-instrument=... and -fxray-never-instrument=... flags. The
501// attributes in source take precedence over these special-case lists.
502//
503// To disable the XRay attributes at build-time, users may define
504// ABSL_NO_XRAY_ATTRIBUTES. Do NOT define ABSL_NO_XRAY_ATTRIBUTES on specific
505// packages/targets, as this may lead to conflicting definitions of functions at
506// link-time.
507//
508#if ABSL_HAVE_CPP_ATTRIBUTE(clang::xray_always_instrument) && \
509 !defined(ABSL_NO_XRAY_ATTRIBUTES)
510#define ABSL_XRAY_ALWAYS_INSTRUMENT [[clang::xray_always_instrument]]
511#define ABSL_XRAY_NEVER_INSTRUMENT [[clang::xray_never_instrument]]
512#if ABSL_HAVE_CPP_ATTRIBUTE(clang::xray_log_args)
513#define ABSL_XRAY_LOG_ARGS(N) \
514 [[clang::xray_always_instrument, clang::xray_log_args(N)]]
515#else
516#define ABSL_XRAY_LOG_ARGS(N) [[clang::xray_always_instrument]]
517#endif
518#else
519#define ABSL_XRAY_ALWAYS_INSTRUMENT
520#define ABSL_XRAY_NEVER_INSTRUMENT
521#define ABSL_XRAY_LOG_ARGS(N)
522#endif
523
524// ABSL_ATTRIBUTE_REINITIALIZES
525//
526// Indicates that a member function reinitializes the entire object to a known
527// state, independent of the previous state of the object.
528//
529// The clang-tidy check bugprone-use-after-move allows member functions marked
530// with this attribute to be called on objects that have been moved from;
531// without the attribute, this would result in a use-after-move warning.
532#if ABSL_HAVE_CPP_ATTRIBUTE(clang::reinitializes)
533#define ABSL_ATTRIBUTE_REINITIALIZES [[clang::reinitializes]]
534#else
535#define ABSL_ATTRIBUTE_REINITIALIZES
536#endif
537
538// -----------------------------------------------------------------------------
539// Variable Attributes
540// -----------------------------------------------------------------------------
541
542// ABSL_ATTRIBUTE_UNUSED
543//
544// Prevents the compiler from complaining about variables that appear unused.
545#if ABSL_HAVE_ATTRIBUTE(unused) || (defined(__GNUC__) && !defined(__clang__))
546#undef ABSL_ATTRIBUTE_UNUSED
547#define ABSL_ATTRIBUTE_UNUSED __attribute__((__unused__))
548#else
549#define ABSL_ATTRIBUTE_UNUSED
550#endif
551
552// ABSL_ATTRIBUTE_INITIAL_EXEC
553//
554// Tells the compiler to use "initial-exec" mode for a thread-local variable.
555// See http://people.redhat.com/drepper/tls.pdf for the gory details.
556#if ABSL_HAVE_ATTRIBUTE(tls_model) || (defined(__GNUC__) && !defined(__clang__))
557#define ABSL_ATTRIBUTE_INITIAL_EXEC __attribute__((tls_model("initial-exec")))
558#else
559#define ABSL_ATTRIBUTE_INITIAL_EXEC
560#endif
561
562// ABSL_ATTRIBUTE_PACKED
563//
564// Prevents the compiler from padding a structure to natural alignment
565#if ABSL_HAVE_ATTRIBUTE(packed) || (defined(__GNUC__) && !defined(__clang__))
566#define ABSL_ATTRIBUTE_PACKED __attribute__((__packed__))
567#else
568#define ABSL_ATTRIBUTE_PACKED
569#endif
570
571// ABSL_ATTRIBUTE_FUNC_ALIGN
572//
573// Tells the compiler to align the function start at least to certain
574// alignment boundary
575#if ABSL_HAVE_ATTRIBUTE(aligned) || (defined(__GNUC__) && !defined(__clang__))
576#define ABSL_ATTRIBUTE_FUNC_ALIGN(bytes) __attribute__((aligned(bytes)))
577#else
578#define ABSL_ATTRIBUTE_FUNC_ALIGN(bytes)
579#endif
580
581// ABSL_CONST_INIT
582//
583// A variable declaration annotated with the `ABSL_CONST_INIT` attribute will
584// not compile (on supported platforms) unless the variable has a constant
585// initializer. This is useful for variables with static and thread storage
586// duration, because it guarantees that they will not suffer from the so-called
587// "static init order fiasco". Prefer to put this attribute on the most visible
588// declaration of the variable, if there's more than one, because code that
589// accesses the variable can then use the attribute for optimization.
590//
591// Example:
592//
593// class MyClass {
594// public:
595// ABSL_CONST_INIT static MyType my_var;
596// };
597//
598// MyType MyClass::my_var = MakeMyType(...);
599//
600// Note that this attribute is redundant if the variable is declared constexpr.
601#if ABSL_HAVE_CPP_ATTRIBUTE(clang::require_constant_initialization)
602// NOLINTNEXTLINE(whitespace/braces)
603#define ABSL_CONST_INIT [[clang::require_constant_initialization]]
604#else
605#define ABSL_CONST_INIT
606#endif // ABSL_HAVE_CPP_ATTRIBUTE(clang::require_constant_initialization)
607
608#endif // ABSL_BASE_ATTRIBUTES_H_
609