attributes.h
Go to the documentation of this file.
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__) && defined(ADDRESS_SANITIZER)
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(__GNUC__) && defined(MEMORY_SANITIZER)
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__) && defined(THREAD_SANITIZER)
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_


abseil_cpp
Author(s):
autogenerated on Mon Feb 28 2022 21:31:17