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 further information. 161 // The MinGW compiler doesn't complain about the weak attribute until the link 162 // step, presumably because Windows doesn't use ELF binaries. 163 #if (ABSL_HAVE_ATTRIBUTE(weak) || \ 164 (defined(__GNUC__) && !defined(__clang__))) && \ 165 !(defined(__llvm__) && defined(_WIN32)) && !defined(__MINGW32__) 166 #undef ABSL_ATTRIBUTE_WEAK 167 #define ABSL_ATTRIBUTE_WEAK __attribute__((weak)) 168 #define ABSL_HAVE_ATTRIBUTE_WEAK 1 169 #else 170 #define ABSL_ATTRIBUTE_WEAK 171 #define ABSL_HAVE_ATTRIBUTE_WEAK 0 172 #endif 173 174 // ABSL_ATTRIBUTE_NONNULL 175 // 176 // Tells the compiler either (a) that a particular function parameter 177 // should be a non-null pointer, or (b) that all pointer arguments should 178 // be non-null. 179 // 180 // Note: As the GCC manual states, "[s]ince non-static C++ methods 181 // have an implicit 'this' argument, the arguments of such methods 182 // should be counted from two, not one." 183 // 184 // Args are indexed starting at 1. 185 // 186 // For non-static class member functions, the implicit `this` argument 187 // is arg 1, and the first explicit argument is arg 2. For static class member 188 // functions, there is no implicit `this`, and the first explicit argument is 189 // arg 1. 190 // 191 // Example: 192 // 193 // /* arg_a cannot be null, but arg_b can */ 194 // void Function(void* arg_a, void* arg_b) ABSL_ATTRIBUTE_NONNULL(1); 195 // 196 // class C { 197 // /* arg_a cannot be null, but arg_b can */ 198 // void Method(void* arg_a, void* arg_b) ABSL_ATTRIBUTE_NONNULL(2); 199 // 200 // /* arg_a cannot be null, but arg_b can */ 201 // static void StaticMethod(void* arg_a, void* arg_b) 202 // ABSL_ATTRIBUTE_NONNULL(1); 203 // }; 204 // 205 // If no arguments are provided, then all pointer arguments should be non-null. 206 // 207 // /* No pointer arguments may be null. */ 208 // void Function(void* arg_a, void* arg_b, int arg_c) ABSL_ATTRIBUTE_NONNULL(); 209 // 210 // NOTE: The GCC nonnull attribute actually accepts a list of arguments, but 211 // ABSL_ATTRIBUTE_NONNULL does not. 212 #if ABSL_HAVE_ATTRIBUTE(nonnull) || (defined(__GNUC__) && !defined(__clang__)) 213 #define ABSL_ATTRIBUTE_NONNULL(arg_index) __attribute__((nonnull(arg_index))) 214 #else 215 #define ABSL_ATTRIBUTE_NONNULL(...) 216 #endif 217 218 // ABSL_ATTRIBUTE_NORETURN 219 // 220 // Tells the compiler that a given function never returns. 221 #if ABSL_HAVE_ATTRIBUTE(noreturn) || (defined(__GNUC__) && !defined(__clang__)) 222 #define ABSL_ATTRIBUTE_NORETURN __attribute__((noreturn)) 223 #elif defined(_MSC_VER) 224 #define ABSL_ATTRIBUTE_NORETURN __declspec(noreturn) 225 #else 226 #define ABSL_ATTRIBUTE_NORETURN 227 #endif 228 229 // ABSL_ATTRIBUTE_NO_SANITIZE_ADDRESS 230 // 231 // Tells the AddressSanitizer (or other memory testing tools) to ignore a given 232 // function. Useful for cases when a function reads random locations on stack, 233 // calls _exit from a cloned subprocess, deliberately accesses buffer 234 // out of bounds or does other scary things with memory. 235 // NOTE: GCC supports AddressSanitizer(asan) since 4.8. 236 // https://gcc.gnu.org/gcc-4.8/changes.html 237 #if defined(__GNUC__) 238 #define ABSL_ATTRIBUTE_NO_SANITIZE_ADDRESS __attribute__((no_sanitize_address)) 239 #else 240 #define ABSL_ATTRIBUTE_NO_SANITIZE_ADDRESS 241 #endif 242 243 // ABSL_ATTRIBUTE_NO_SANITIZE_MEMORY 244 // 245 // Tells the MemorySanitizer to relax the handling of a given function. All 246 // "Use of uninitialized value" warnings from such functions will be suppressed, 247 // and all values loaded from memory will be considered fully initialized. 248 // This attribute is similar to the ADDRESS_SANITIZER attribute above, but deals 249 // with initialized-ness rather than addressability issues. 250 // NOTE: MemorySanitizer(msan) is supported by Clang but not GCC. 251 #if defined(__clang__) 252 #define ABSL_ATTRIBUTE_NO_SANITIZE_MEMORY __attribute__((no_sanitize_memory)) 253 #else 254 #define ABSL_ATTRIBUTE_NO_SANITIZE_MEMORY 255 #endif 256 257 // ABSL_ATTRIBUTE_NO_SANITIZE_THREAD 258 // 259 // Tells the ThreadSanitizer to not instrument a given function. 260 // NOTE: GCC supports ThreadSanitizer(tsan) since 4.8. 261 // https://gcc.gnu.org/gcc-4.8/changes.html 262 #if defined(__GNUC__) 263 #define ABSL_ATTRIBUTE_NO_SANITIZE_THREAD __attribute__((no_sanitize_thread)) 264 #else 265 #define ABSL_ATTRIBUTE_NO_SANITIZE_THREAD 266 #endif 267 268 // ABSL_ATTRIBUTE_NO_SANITIZE_UNDEFINED 269 // 270 // Tells the UndefinedSanitizer to ignore a given function. Useful for cases 271 // where certain behavior (eg. division by zero) is being used intentionally. 272 // NOTE: GCC supports UndefinedBehaviorSanitizer(ubsan) since 4.9. 273 // https://gcc.gnu.org/gcc-4.9/changes.html 274 #if defined(__GNUC__) && \ 275 (defined(UNDEFINED_BEHAVIOR_SANITIZER) || defined(ADDRESS_SANITIZER)) 276 #define ABSL_ATTRIBUTE_NO_SANITIZE_UNDEFINED \ 277 __attribute__((no_sanitize("undefined"))) 278 #else 279 #define ABSL_ATTRIBUTE_NO_SANITIZE_UNDEFINED 280 #endif 281 282 // ABSL_ATTRIBUTE_NO_SANITIZE_CFI 283 // 284 // Tells the ControlFlowIntegrity sanitizer to not instrument a given function. 285 // See https://clang.llvm.org/docs/ControlFlowIntegrity.html for details. 286 #if defined(__GNUC__) && defined(CONTROL_FLOW_INTEGRITY) 287 #define ABSL_ATTRIBUTE_NO_SANITIZE_CFI __attribute__((no_sanitize("cfi"))) 288 #else 289 #define ABSL_ATTRIBUTE_NO_SANITIZE_CFI 290 #endif 291 292 // ABSL_ATTRIBUTE_NO_SANITIZE_SAFESTACK 293 // 294 // Tells the SafeStack to not instrument a given function. 295 // See https://clang.llvm.org/docs/SafeStack.html for details. 296 #if defined(__GNUC__) && defined(SAFESTACK_SANITIZER) 297 #define ABSL_ATTRIBUTE_NO_SANITIZE_SAFESTACK \ 298 __attribute__((no_sanitize("safe-stack"))) 299 #else 300 #define ABSL_ATTRIBUTE_NO_SANITIZE_SAFESTACK 301 #endif 302 303 // ABSL_ATTRIBUTE_RETURNS_NONNULL 304 // 305 // Tells the compiler that a particular function never returns a null pointer. 306 #if ABSL_HAVE_ATTRIBUTE(returns_nonnull) || \ 307 (defined(__GNUC__) && \ 308 (__GNUC__ > 5 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 9)) && \ 309 !defined(__clang__)) 310 #define ABSL_ATTRIBUTE_RETURNS_NONNULL __attribute__((returns_nonnull)) 311 #else 312 #define ABSL_ATTRIBUTE_RETURNS_NONNULL 313 #endif 314 315 // ABSL_HAVE_ATTRIBUTE_SECTION 316 // 317 // Indicates whether labeled sections are supported. Weak symbol support is 318 // a prerequisite. Labeled sections are not supported on Darwin/iOS. 319 #ifdef ABSL_HAVE_ATTRIBUTE_SECTION 320 #error ABSL_HAVE_ATTRIBUTE_SECTION cannot be directly set 321 #elif (ABSL_HAVE_ATTRIBUTE(section) || \ 322 (defined(__GNUC__) && !defined(__clang__))) && \ 323 !defined(__APPLE__) && ABSL_HAVE_ATTRIBUTE_WEAK 324 #define ABSL_HAVE_ATTRIBUTE_SECTION 1 325 326 // ABSL_ATTRIBUTE_SECTION 327 // 328 // Tells the compiler/linker to put a given function into a section and define 329 // `__start_ ## name` and `__stop_ ## name` symbols to bracket the section. 330 // This functionality is supported by GNU linker. Any function annotated with 331 // `ABSL_ATTRIBUTE_SECTION` must not be inlined, or it will be placed into 332 // whatever section its caller is placed into. 333 // 334 #ifndef ABSL_ATTRIBUTE_SECTION 335 #define ABSL_ATTRIBUTE_SECTION(name) \ 336 __attribute__((section(#name))) __attribute__((noinline)) 337 #endif 338 339 340 // ABSL_ATTRIBUTE_SECTION_VARIABLE 341 // 342 // Tells the compiler/linker to put a given variable into a section and define 343 // `__start_ ## name` and `__stop_ ## name` symbols to bracket the section. 344 // This functionality is supported by GNU linker. 345 #ifndef ABSL_ATTRIBUTE_SECTION_VARIABLE 346 #define ABSL_ATTRIBUTE_SECTION_VARIABLE(name) __attribute__((section(#name))) 347 #endif 348 349 // ABSL_DECLARE_ATTRIBUTE_SECTION_VARS 350 // 351 // A weak section declaration to be used as a global declaration 352 // for ABSL_ATTRIBUTE_SECTION_START|STOP(name) to compile and link 353 // even without functions with ABSL_ATTRIBUTE_SECTION(name). 354 // ABSL_DEFINE_ATTRIBUTE_SECTION should be in the exactly one file; it's 355 // a no-op on ELF but not on Mach-O. 356 // 357 #ifndef ABSL_DECLARE_ATTRIBUTE_SECTION_VARS 358 #define ABSL_DECLARE_ATTRIBUTE_SECTION_VARS(name) \ 359 extern char __start_##name[] ABSL_ATTRIBUTE_WEAK; \ 360 extern char __stop_##name[] ABSL_ATTRIBUTE_WEAK 361 #endif 362 #ifndef ABSL_DEFINE_ATTRIBUTE_SECTION_VARS 363 #define ABSL_INIT_ATTRIBUTE_SECTION_VARS(name) 364 #define ABSL_DEFINE_ATTRIBUTE_SECTION_VARS(name) 365 #endif 366 367 // ABSL_ATTRIBUTE_SECTION_START 368 // 369 // Returns `void*` pointers to start/end of a section of code with 370 // functions having ABSL_ATTRIBUTE_SECTION(name). 371 // Returns 0 if no such functions exist. 372 // One must ABSL_DECLARE_ATTRIBUTE_SECTION_VARS(name) for this to compile and 373 // link. 374 // 375 #define ABSL_ATTRIBUTE_SECTION_START(name) \ 376 (reinterpret_cast<void *>(__start_##name)) 377 #define ABSL_ATTRIBUTE_SECTION_STOP(name) \ 378 (reinterpret_cast<void *>(__stop_##name)) 379 380 #else // !ABSL_HAVE_ATTRIBUTE_SECTION 381 382 #define ABSL_HAVE_ATTRIBUTE_SECTION 0 383 384 // provide dummy definitions 385 #define ABSL_ATTRIBUTE_SECTION(name) 386 #define ABSL_ATTRIBUTE_SECTION_VARIABLE(name) 387 #define ABSL_INIT_ATTRIBUTE_SECTION_VARS(name) 388 #define ABSL_DEFINE_ATTRIBUTE_SECTION_VARS(name) 389 #define ABSL_DECLARE_ATTRIBUTE_SECTION_VARS(name) 390 #define ABSL_ATTRIBUTE_SECTION_START(name) (reinterpret_cast<void *>(0)) 391 #define ABSL_ATTRIBUTE_SECTION_STOP(name) (reinterpret_cast<void *>(0)) 392 393 #endif // ABSL_ATTRIBUTE_SECTION 394 395 // ABSL_ATTRIBUTE_STACK_ALIGN_FOR_OLD_LIBC 396 // 397 // Support for aligning the stack on 32-bit x86. 398 #if ABSL_HAVE_ATTRIBUTE(force_align_arg_pointer) || \ 399 (defined(__GNUC__) && !defined(__clang__)) 400 #if defined(__i386__) 401 #define ABSL_ATTRIBUTE_STACK_ALIGN_FOR_OLD_LIBC \ 402 __attribute__((force_align_arg_pointer)) 403 #define ABSL_REQUIRE_STACK_ALIGN_TRAMPOLINE (0) 404 #elif defined(__x86_64__) 405 #define ABSL_REQUIRE_STACK_ALIGN_TRAMPOLINE (1) 406 #define ABSL_ATTRIBUTE_STACK_ALIGN_FOR_OLD_LIBC 407 #else // !__i386__ && !__x86_64 408 #define ABSL_REQUIRE_STACK_ALIGN_TRAMPOLINE (0) 409 #define ABSL_ATTRIBUTE_STACK_ALIGN_FOR_OLD_LIBC 410 #endif // __i386__ 411 #else 412 #define ABSL_ATTRIBUTE_STACK_ALIGN_FOR_OLD_LIBC 413 #define ABSL_REQUIRE_STACK_ALIGN_TRAMPOLINE (0) 414 #endif 415 416 // ABSL_MUST_USE_RESULT 417 // 418 // Tells the compiler to warn about unused results. 419 // 420 // When annotating a function, it must appear as the first part of the 421 // declaration or definition. The compiler will warn if the return value from 422 // such a function is unused: 423 // 424 // ABSL_MUST_USE_RESULT Sprocket* AllocateSprocket(); 425 // AllocateSprocket(); // Triggers a warning. 426 // 427 // When annotating a class, it is equivalent to annotating every function which 428 // returns an instance. 429 // 430 // class ABSL_MUST_USE_RESULT Sprocket {}; 431 // Sprocket(); // Triggers a warning. 432 // 433 // Sprocket MakeSprocket(); 434 // MakeSprocket(); // Triggers a warning. 435 // 436 // Note that references and pointers are not instances: 437 // 438 // Sprocket* SprocketPointer(); 439 // SprocketPointer(); // Does *not* trigger a warning. 440 // 441 // ABSL_MUST_USE_RESULT allows using cast-to-void to suppress the unused result 442 // warning. For that, warn_unused_result is used only for clang but not for gcc. 443 // https://gcc.gnu.org/bugzilla/show_bug.cgi?id=66425 444 // 445 // Note: past advice was to place the macro after the argument list. 446 #if ABSL_HAVE_ATTRIBUTE(nodiscard) 447 #define ABSL_MUST_USE_RESULT [[nodiscard]] 448 #elif defined(__clang__) && ABSL_HAVE_ATTRIBUTE(warn_unused_result) 449 #define ABSL_MUST_USE_RESULT __attribute__((warn_unused_result)) 450 #else 451 #define ABSL_MUST_USE_RESULT 452 #endif 453 454 // ABSL_ATTRIBUTE_HOT, ABSL_ATTRIBUTE_COLD 455 // 456 // Tells GCC that a function is hot or cold. GCC can use this information to 457 // improve static analysis, i.e. a conditional branch to a cold function 458 // is likely to be not-taken. 459 // This annotation is used for function declarations. 460 // 461 // Example: 462 // 463 // int foo() ABSL_ATTRIBUTE_HOT; 464 #if ABSL_HAVE_ATTRIBUTE(hot) || (defined(__GNUC__) && !defined(__clang__)) 465 #define ABSL_ATTRIBUTE_HOT __attribute__((hot)) 466 #else 467 #define ABSL_ATTRIBUTE_HOT 468 #endif 469 470 #if ABSL_HAVE_ATTRIBUTE(cold) || (defined(__GNUC__) && !defined(__clang__)) 471 #define ABSL_ATTRIBUTE_COLD __attribute__((cold)) 472 #else 473 #define ABSL_ATTRIBUTE_COLD 474 #endif 475 476 // ABSL_XRAY_ALWAYS_INSTRUMENT, ABSL_XRAY_NEVER_INSTRUMENT, ABSL_XRAY_LOG_ARGS 477 // 478 // We define the ABSL_XRAY_ALWAYS_INSTRUMENT and ABSL_XRAY_NEVER_INSTRUMENT 479 // macro used as an attribute to mark functions that must always or never be 480 // instrumented by XRay. Currently, this is only supported in Clang/LLVM. 481 // 482 // For reference on the LLVM XRay instrumentation, see 483 // http://llvm.org/docs/XRay.html. 484 // 485 // A function with the XRAY_ALWAYS_INSTRUMENT macro attribute in its declaration 486 // will always get the XRay instrumentation sleds. These sleds may introduce 487 // some binary size and runtime overhead and must be used sparingly. 488 // 489 // These attributes only take effect when the following conditions are met: 490 // 491 // * The file/target is built in at least C++11 mode, with a Clang compiler 492 // that supports XRay attributes. 493 // * The file/target is built with the -fxray-instrument flag set for the 494 // Clang/LLVM compiler. 495 // * The function is defined in the translation unit (the compiler honors the 496 // attribute in either the definition or the declaration, and must match). 497 // 498 // There are cases when, even when building with XRay instrumentation, users 499 // might want to control specifically which functions are instrumented for a 500 // particular build using special-case lists provided to the compiler. These 501 // special case lists are provided to Clang via the 502 // -fxray-always-instrument=... and -fxray-never-instrument=... flags. The 503 // attributes in source take precedence over these special-case lists. 504 // 505 // To disable the XRay attributes at build-time, users may define 506 // ABSL_NO_XRAY_ATTRIBUTES. Do NOT define ABSL_NO_XRAY_ATTRIBUTES on specific 507 // packages/targets, as this may lead to conflicting definitions of functions at 508 // link-time. 509 // 510 #if ABSL_HAVE_CPP_ATTRIBUTE(clang::xray_always_instrument) && \ 511 !defined(ABSL_NO_XRAY_ATTRIBUTES) 512 #define ABSL_XRAY_ALWAYS_INSTRUMENT [[clang::xray_always_instrument]] 513 #define ABSL_XRAY_NEVER_INSTRUMENT [[clang::xray_never_instrument]] 514 #if ABSL_HAVE_CPP_ATTRIBUTE(clang::xray_log_args) 515 #define ABSL_XRAY_LOG_ARGS(N) \ 516 [[clang::xray_always_instrument, clang::xray_log_args(N)]] 517 #else 518 #define ABSL_XRAY_LOG_ARGS(N) [[clang::xray_always_instrument]] 519 #endif 520 #else 521 #define ABSL_XRAY_ALWAYS_INSTRUMENT 522 #define ABSL_XRAY_NEVER_INSTRUMENT 523 #define ABSL_XRAY_LOG_ARGS(N) 524 #endif 525 526 // ABSL_ATTRIBUTE_REINITIALIZES 527 // 528 // Indicates that a member function reinitializes the entire object to a known 529 // state, independent of the previous state of the object. 530 // 531 // The clang-tidy check bugprone-use-after-move allows member functions marked 532 // with this attribute to be called on objects that have been moved from; 533 // without the attribute, this would result in a use-after-move warning. 534 #if ABSL_HAVE_CPP_ATTRIBUTE(clang::reinitializes) 535 #define ABSL_ATTRIBUTE_REINITIALIZES [[clang::reinitializes]] 536 #else 537 #define ABSL_ATTRIBUTE_REINITIALIZES 538 #endif 539 540 // ----------------------------------------------------------------------------- 541 // Variable Attributes 542 // ----------------------------------------------------------------------------- 543 544 // ABSL_ATTRIBUTE_UNUSED 545 // 546 // Prevents the compiler from complaining about variables that appear unused. 547 #if ABSL_HAVE_ATTRIBUTE(unused) || (defined(__GNUC__) && !defined(__clang__)) 548 #undef ABSL_ATTRIBUTE_UNUSED 549 #define ABSL_ATTRIBUTE_UNUSED __attribute__((__unused__)) 550 #else 551 #define ABSL_ATTRIBUTE_UNUSED 552 #endif 553 554 // ABSL_ATTRIBUTE_INITIAL_EXEC 555 // 556 // Tells the compiler to use "initial-exec" mode for a thread-local variable. 557 // See http://people.redhat.com/drepper/tls.pdf for the gory details. 558 #if ABSL_HAVE_ATTRIBUTE(tls_model) || (defined(__GNUC__) && !defined(__clang__)) 559 #define ABSL_ATTRIBUTE_INITIAL_EXEC __attribute__((tls_model("initial-exec"))) 560 #else 561 #define ABSL_ATTRIBUTE_INITIAL_EXEC 562 #endif 563 564 // ABSL_ATTRIBUTE_PACKED 565 // 566 // Instructs the compiler not to use natural alignment for a tagged data 567 // structure, but instead to reduce its alignment to 1. This attribute can 568 // either be applied to members of a structure or to a structure in its 569 // entirety. Applying this attribute (judiciously) to a structure in its 570 // entirety to optimize the memory footprint of very commonly-used structs is 571 // fine. Do not apply this attribute to a structure in its entirety if the 572 // purpose is to control the offsets of the members in the structure. Instead, 573 // apply this attribute only to structure members that need it. 574 // 575 // When applying ABSL_ATTRIBUTE_PACKED only to specific structure members the 576 // natural alignment of structure members not annotated is preserved. Aligned 577 // member accesses are faster than non-aligned member accesses even if the 578 // targeted microprocessor supports non-aligned accesses. 579 #if ABSL_HAVE_ATTRIBUTE(packed) || (defined(__GNUC__) && !defined(__clang__)) 580 #define ABSL_ATTRIBUTE_PACKED __attribute__((__packed__)) 581 #else 582 #define ABSL_ATTRIBUTE_PACKED 583 #endif 584 585 // ABSL_ATTRIBUTE_FUNC_ALIGN 586 // 587 // Tells the compiler to align the function start at least to certain 588 // alignment boundary 589 #if ABSL_HAVE_ATTRIBUTE(aligned) || (defined(__GNUC__) && !defined(__clang__)) 590 #define ABSL_ATTRIBUTE_FUNC_ALIGN(bytes) __attribute__((aligned(bytes))) 591 #else 592 #define ABSL_ATTRIBUTE_FUNC_ALIGN(bytes) 593 #endif 594 595 // ABSL_CONST_INIT 596 // 597 // A variable declaration annotated with the `ABSL_CONST_INIT` attribute will 598 // not compile (on supported platforms) unless the variable has a constant 599 // initializer. This is useful for variables with static and thread storage 600 // duration, because it guarantees that they will not suffer from the so-called 601 // "static init order fiasco". Prefer to put this attribute on the most visible 602 // declaration of the variable, if there's more than one, because code that 603 // accesses the variable can then use the attribute for optimization. 604 // 605 // Example: 606 // 607 // class MyClass { 608 // public: 609 // ABSL_CONST_INIT static MyType my_var; 610 // }; 611 // 612 // MyType MyClass::my_var = MakeMyType(...); 613 // 614 // Note that this attribute is redundant if the variable is declared constexpr. 615 #if ABSL_HAVE_CPP_ATTRIBUTE(clang::require_constant_initialization) 616 #define ABSL_CONST_INIT [[clang::require_constant_initialization]] 617 #else 618 #define ABSL_CONST_INIT 619 #endif // ABSL_HAVE_CPP_ATTRIBUTE(clang::require_constant_initialization) 620 621 #endif // ABSL_BASE_ATTRIBUTES_H_ 622