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 #ifndef ABSL_BASE_ATTRIBUTES_H_ 37 #define ABSL_BASE_ATTRIBUTES_H_ 38 39 #include "absl/base/config.h" 40 41 // ABSL_HAVE_ATTRIBUTE 42 // 43 // A function-like feature checking macro that is a wrapper around 44 // `__has_attribute`, which is defined by GCC 5+ and Clang and evaluates to a 45 // nonzero constant integer if the attribute is supported or 0 if not. 46 // 47 // It evaluates to zero if `__has_attribute` is not defined by the compiler. 48 // 49 // GCC: https://gcc.gnu.org/gcc-5/changes.html 50 // Clang: https://clang.llvm.org/docs/LanguageExtensions.html 51 #ifdef __has_attribute 52 #define ABSL_HAVE_ATTRIBUTE(x) __has_attribute(x) 53 #else 54 #define ABSL_HAVE_ATTRIBUTE(x) 0 55 #endif 56 57 // ABSL_HAVE_CPP_ATTRIBUTE 58 // 59 // A function-like feature checking macro that accepts C++11 style attributes. 60 // It's a wrapper around `__has_cpp_attribute`, defined by ISO C++ SD-6 61 // (https://en.cppreference.com/w/cpp/experimental/feature_test). If we don't 62 // find `__has_cpp_attribute`, will evaluate to 0. 63 #if defined(__cplusplus) && defined(__has_cpp_attribute) 64 // NOTE: requiring __cplusplus above should not be necessary, but 65 // works around https://bugs.llvm.org/show_bug.cgi?id=23435. 66 #define ABSL_HAVE_CPP_ATTRIBUTE(x) __has_cpp_attribute(x) 67 #else 68 #define ABSL_HAVE_CPP_ATTRIBUTE(x) 0 69 #endif 70 71 // ----------------------------------------------------------------------------- 72 // Function Attributes 73 // ----------------------------------------------------------------------------- 74 // 75 // GCC: https://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html 76 // Clang: https://clang.llvm.org/docs/AttributeReference.html 77 78 // ABSL_PRINTF_ATTRIBUTE 79 // ABSL_SCANF_ATTRIBUTE 80 // 81 // Tells the compiler to perform `printf` format string checking if the 82 // compiler supports it; see the 'format' attribute in 83 // <https://gcc.gnu.org/onlinedocs/gcc-4.7.0/gcc/Function-Attributes.html>. 84 // 85 // Note: As the GCC manual states, "[s]ince non-static C++ methods 86 // have an implicit 'this' argument, the arguments of such methods 87 // should be counted from two, not one." 88 #if ABSL_HAVE_ATTRIBUTE(format) || (defined(__GNUC__) && !defined(__clang__)) 89 #define ABSL_PRINTF_ATTRIBUTE(string_index, first_to_check) \ 90 __attribute__((__format__(__printf__, string_index, first_to_check))) 91 #define ABSL_SCANF_ATTRIBUTE(string_index, first_to_check) \ 92 __attribute__((__format__(__scanf__, string_index, first_to_check))) 93 #else 94 #define ABSL_PRINTF_ATTRIBUTE(string_index, first_to_check) 95 #define ABSL_SCANF_ATTRIBUTE(string_index, first_to_check) 96 #endif 97 98 // ABSL_ATTRIBUTE_ALWAYS_INLINE 99 // ABSL_ATTRIBUTE_NOINLINE 100 // 101 // Forces functions to either inline or not inline. Introduced in gcc 3.1. 102 #if ABSL_HAVE_ATTRIBUTE(always_inline) || \ 103 (defined(__GNUC__) && !defined(__clang__)) 104 #define ABSL_ATTRIBUTE_ALWAYS_INLINE __attribute__((always_inline)) 105 #define ABSL_HAVE_ATTRIBUTE_ALWAYS_INLINE 1 106 #else 107 #define ABSL_ATTRIBUTE_ALWAYS_INLINE 108 #endif 109 110 #if ABSL_HAVE_ATTRIBUTE(noinline) || (defined(__GNUC__) && !defined(__clang__)) 111 #define ABSL_ATTRIBUTE_NOINLINE __attribute__((noinline)) 112 #define ABSL_HAVE_ATTRIBUTE_NOINLINE 1 113 #else 114 #define ABSL_ATTRIBUTE_NOINLINE 115 #endif 116 117 // ABSL_ATTRIBUTE_NO_TAIL_CALL 118 // 119 // Prevents the compiler from optimizing away stack frames for functions which 120 // end in a call to another function. 121 #if ABSL_HAVE_ATTRIBUTE(disable_tail_calls) 122 #define ABSL_HAVE_ATTRIBUTE_NO_TAIL_CALL 1 123 #define ABSL_ATTRIBUTE_NO_TAIL_CALL __attribute__((disable_tail_calls)) 124 #elif defined(__GNUC__) && !defined(__clang__) 125 #define ABSL_HAVE_ATTRIBUTE_NO_TAIL_CALL 1 126 #define ABSL_ATTRIBUTE_NO_TAIL_CALL \ 127 __attribute__((optimize("no-optimize-sibling-calls"))) 128 #else 129 #define ABSL_ATTRIBUTE_NO_TAIL_CALL 130 #define ABSL_HAVE_ATTRIBUTE_NO_TAIL_CALL 0 131 #endif 132 133 // ABSL_ATTRIBUTE_WEAK 134 // 135 // Tags a function as weak for the purposes of compilation and linking. 136 // Weak attributes currently do not work properly in LLVM's Windows backend, 137 // so disable them there. See https://bugs.llvm.org/show_bug.cgi?id=37598 138 // for further information. 139 // The MinGW compiler doesn't complain about the weak attribute until the link 140 // step, presumably because Windows doesn't use ELF binaries. 141 #if (ABSL_HAVE_ATTRIBUTE(weak) || \ 142 (defined(__GNUC__) && !defined(__clang__))) && \ 143 !(defined(__llvm__) && defined(_WIN32)) && !defined(__MINGW32__) 144 #undef ABSL_ATTRIBUTE_WEAK 145 #define ABSL_ATTRIBUTE_WEAK __attribute__((weak)) 146 #define ABSL_HAVE_ATTRIBUTE_WEAK 1 147 #else 148 #define ABSL_ATTRIBUTE_WEAK 149 #define ABSL_HAVE_ATTRIBUTE_WEAK 0 150 #endif 151 152 // ABSL_ATTRIBUTE_NONNULL 153 // 154 // Tells the compiler either (a) that a particular function parameter 155 // should be a non-null pointer, or (b) that all pointer arguments should 156 // be non-null. 157 // 158 // Note: As the GCC manual states, "[s]ince non-static C++ methods 159 // have an implicit 'this' argument, the arguments of such methods 160 // should be counted from two, not one." 161 // 162 // Args are indexed starting at 1. 163 // 164 // For non-static class member functions, the implicit `this` argument 165 // is arg 1, and the first explicit argument is arg 2. For static class member 166 // functions, there is no implicit `this`, and the first explicit argument is 167 // arg 1. 168 // 169 // Example: 170 // 171 // /* arg_a cannot be null, but arg_b can */ 172 // void Function(void* arg_a, void* arg_b) ABSL_ATTRIBUTE_NONNULL(1); 173 // 174 // class C { 175 // /* arg_a cannot be null, but arg_b can */ 176 // void Method(void* arg_a, void* arg_b) ABSL_ATTRIBUTE_NONNULL(2); 177 // 178 // /* arg_a cannot be null, but arg_b can */ 179 // static void StaticMethod(void* arg_a, void* arg_b) 180 // ABSL_ATTRIBUTE_NONNULL(1); 181 // }; 182 // 183 // If no arguments are provided, then all pointer arguments should be non-null. 184 // 185 // /* No pointer arguments may be null. */ 186 // void Function(void* arg_a, void* arg_b, int arg_c) ABSL_ATTRIBUTE_NONNULL(); 187 // 188 // NOTE: The GCC nonnull attribute actually accepts a list of arguments, but 189 // ABSL_ATTRIBUTE_NONNULL does not. 190 #if ABSL_HAVE_ATTRIBUTE(nonnull) || (defined(__GNUC__) && !defined(__clang__)) 191 #define ABSL_ATTRIBUTE_NONNULL(arg_index) __attribute__((nonnull(arg_index))) 192 #else 193 #define ABSL_ATTRIBUTE_NONNULL(...) 194 #endif 195 196 // ABSL_ATTRIBUTE_NORETURN 197 // 198 // Tells the compiler that a given function never returns. 199 #if ABSL_HAVE_ATTRIBUTE(noreturn) || (defined(__GNUC__) && !defined(__clang__)) 200 #define ABSL_ATTRIBUTE_NORETURN __attribute__((noreturn)) 201 #elif defined(_MSC_VER) 202 #define ABSL_ATTRIBUTE_NORETURN __declspec(noreturn) 203 #else 204 #define ABSL_ATTRIBUTE_NORETURN 205 #endif 206 207 // ABSL_ATTRIBUTE_NO_SANITIZE_ADDRESS 208 // 209 // Tells the AddressSanitizer (or other memory testing tools) to ignore a given 210 // function. Useful for cases when a function reads random locations on stack, 211 // calls _exit from a cloned subprocess, deliberately accesses buffer 212 // out of bounds or does other scary things with memory. 213 // NOTE: GCC supports AddressSanitizer(asan) since 4.8. 214 // https://gcc.gnu.org/gcc-4.8/changes.html 215 #if ABSL_HAVE_ATTRIBUTE(no_sanitize_address) 216 #define ABSL_ATTRIBUTE_NO_SANITIZE_ADDRESS __attribute__((no_sanitize_address)) 217 #else 218 #define ABSL_ATTRIBUTE_NO_SANITIZE_ADDRESS 219 #endif 220 221 // ABSL_ATTRIBUTE_NO_SANITIZE_MEMORY 222 // 223 // Tells the MemorySanitizer to relax the handling of a given function. All "Use 224 // of uninitialized value" warnings from such functions will be suppressed, and 225 // all values loaded from memory will be considered fully initialized. This 226 // attribute is similar to the ABSL_ATTRIBUTE_NO_SANITIZE_ADDRESS attribute 227 // above, but deals with initialized-ness rather than addressability issues. 228 // NOTE: MemorySanitizer(msan) is supported by Clang but not GCC. 229 #if ABSL_HAVE_ATTRIBUTE(no_sanitize_memory) 230 #define ABSL_ATTRIBUTE_NO_SANITIZE_MEMORY __attribute__((no_sanitize_memory)) 231 #else 232 #define ABSL_ATTRIBUTE_NO_SANITIZE_MEMORY 233 #endif 234 235 // ABSL_ATTRIBUTE_NO_SANITIZE_THREAD 236 // 237 // Tells the ThreadSanitizer to not instrument a given function. 238 // NOTE: GCC supports ThreadSanitizer(tsan) since 4.8. 239 // https://gcc.gnu.org/gcc-4.8/changes.html 240 #if ABSL_HAVE_ATTRIBUTE(no_sanitize_thread) 241 #define ABSL_ATTRIBUTE_NO_SANITIZE_THREAD __attribute__((no_sanitize_thread)) 242 #else 243 #define ABSL_ATTRIBUTE_NO_SANITIZE_THREAD 244 #endif 245 246 // ABSL_ATTRIBUTE_NO_SANITIZE_UNDEFINED 247 // 248 // Tells the UndefinedSanitizer to ignore a given function. Useful for cases 249 // where certain behavior (eg. division by zero) is being used intentionally. 250 // NOTE: GCC supports UndefinedBehaviorSanitizer(ubsan) since 4.9. 251 // https://gcc.gnu.org/gcc-4.9/changes.html 252 #if ABSL_HAVE_ATTRIBUTE(no_sanitize_undefined) 253 #define ABSL_ATTRIBUTE_NO_SANITIZE_UNDEFINED \ 254 __attribute__((no_sanitize_undefined)) 255 #elif ABSL_HAVE_ATTRIBUTE(no_sanitize) 256 #define ABSL_ATTRIBUTE_NO_SANITIZE_UNDEFINED \ 257 __attribute__((no_sanitize("undefined"))) 258 #else 259 #define ABSL_ATTRIBUTE_NO_SANITIZE_UNDEFINED 260 #endif 261 262 // ABSL_ATTRIBUTE_NO_SANITIZE_CFI 263 // 264 // Tells the ControlFlowIntegrity sanitizer to not instrument a given function. 265 // See https://clang.llvm.org/docs/ControlFlowIntegrity.html for details. 266 #if ABSL_HAVE_ATTRIBUTE(no_sanitize) 267 #define ABSL_ATTRIBUTE_NO_SANITIZE_CFI __attribute__((no_sanitize("cfi"))) 268 #else 269 #define ABSL_ATTRIBUTE_NO_SANITIZE_CFI 270 #endif 271 272 // ABSL_ATTRIBUTE_NO_SANITIZE_SAFESTACK 273 // 274 // Tells the SafeStack to not instrument a given function. 275 // See https://clang.llvm.org/docs/SafeStack.html for details. 276 #if ABSL_HAVE_ATTRIBUTE(no_sanitize) 277 #define ABSL_ATTRIBUTE_NO_SANITIZE_SAFESTACK \ 278 __attribute__((no_sanitize("safe-stack"))) 279 #else 280 #define ABSL_ATTRIBUTE_NO_SANITIZE_SAFESTACK 281 #endif 282 283 // ABSL_ATTRIBUTE_RETURNS_NONNULL 284 // 285 // Tells the compiler that a particular function never returns a null pointer. 286 #if ABSL_HAVE_ATTRIBUTE(returns_nonnull) || \ 287 (defined(__GNUC__) && \ 288 (__GNUC__ > 5 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 9)) && \ 289 !defined(__clang__)) 290 #define ABSL_ATTRIBUTE_RETURNS_NONNULL __attribute__((returns_nonnull)) 291 #else 292 #define ABSL_ATTRIBUTE_RETURNS_NONNULL 293 #endif 294 295 // ABSL_HAVE_ATTRIBUTE_SECTION 296 // 297 // Indicates whether labeled sections are supported. Weak symbol support is 298 // a prerequisite. Labeled sections are not supported on Darwin/iOS. 299 #ifdef ABSL_HAVE_ATTRIBUTE_SECTION 300 #error ABSL_HAVE_ATTRIBUTE_SECTION cannot be directly set 301 #elif (ABSL_HAVE_ATTRIBUTE(section) || \ 302 (defined(__GNUC__) && !defined(__clang__))) && \ 303 !defined(__APPLE__) && ABSL_HAVE_ATTRIBUTE_WEAK 304 #define ABSL_HAVE_ATTRIBUTE_SECTION 1 305 306 // ABSL_ATTRIBUTE_SECTION 307 // 308 // Tells the compiler/linker to put a given function into a section and define 309 // `__start_ ## name` and `__stop_ ## name` symbols to bracket the section. 310 // This functionality is supported by GNU linker. Any function annotated with 311 // `ABSL_ATTRIBUTE_SECTION` must not be inlined, or it will be placed into 312 // whatever section its caller is placed into. 313 // 314 #ifndef ABSL_ATTRIBUTE_SECTION 315 #define ABSL_ATTRIBUTE_SECTION(name) \ 316 __attribute__((section(#name))) __attribute__((noinline)) 317 #endif 318 319 320 // ABSL_ATTRIBUTE_SECTION_VARIABLE 321 // 322 // Tells the compiler/linker to put a given variable into a section and define 323 // `__start_ ## name` and `__stop_ ## name` symbols to bracket the section. 324 // This functionality is supported by GNU linker. 325 #ifndef ABSL_ATTRIBUTE_SECTION_VARIABLE 326 #define ABSL_ATTRIBUTE_SECTION_VARIABLE(name) __attribute__((section(#name))) 327 #endif 328 329 // ABSL_DECLARE_ATTRIBUTE_SECTION_VARS 330 // 331 // A weak section declaration to be used as a global declaration 332 // for ABSL_ATTRIBUTE_SECTION_START|STOP(name) to compile and link 333 // even without functions with ABSL_ATTRIBUTE_SECTION(name). 334 // ABSL_DEFINE_ATTRIBUTE_SECTION should be in the exactly one file; it's 335 // a no-op on ELF but not on Mach-O. 336 // 337 #ifndef ABSL_DECLARE_ATTRIBUTE_SECTION_VARS 338 #define ABSL_DECLARE_ATTRIBUTE_SECTION_VARS(name) \ 339 extern char __start_##name[] ABSL_ATTRIBUTE_WEAK; \ 340 extern char __stop_##name[] ABSL_ATTRIBUTE_WEAK 341 #endif 342 #ifndef ABSL_DEFINE_ATTRIBUTE_SECTION_VARS 343 #define ABSL_INIT_ATTRIBUTE_SECTION_VARS(name) 344 #define ABSL_DEFINE_ATTRIBUTE_SECTION_VARS(name) 345 #endif 346 347 // ABSL_ATTRIBUTE_SECTION_START 348 // 349 // Returns `void*` pointers to start/end of a section of code with 350 // functions having ABSL_ATTRIBUTE_SECTION(name). 351 // Returns 0 if no such functions exist. 352 // One must ABSL_DECLARE_ATTRIBUTE_SECTION_VARS(name) for this to compile and 353 // link. 354 // 355 #define ABSL_ATTRIBUTE_SECTION_START(name) \ 356 (reinterpret_cast<void *>(__start_##name)) 357 #define ABSL_ATTRIBUTE_SECTION_STOP(name) \ 358 (reinterpret_cast<void *>(__stop_##name)) 359 360 #else // !ABSL_HAVE_ATTRIBUTE_SECTION 361 362 #define ABSL_HAVE_ATTRIBUTE_SECTION 0 363 364 // provide dummy definitions 365 #define ABSL_ATTRIBUTE_SECTION(name) 366 #define ABSL_ATTRIBUTE_SECTION_VARIABLE(name) 367 #define ABSL_INIT_ATTRIBUTE_SECTION_VARS(name) 368 #define ABSL_DEFINE_ATTRIBUTE_SECTION_VARS(name) 369 #define ABSL_DECLARE_ATTRIBUTE_SECTION_VARS(name) 370 #define ABSL_ATTRIBUTE_SECTION_START(name) (reinterpret_cast<void *>(0)) 371 #define ABSL_ATTRIBUTE_SECTION_STOP(name) (reinterpret_cast<void *>(0)) 372 373 #endif // ABSL_ATTRIBUTE_SECTION 374 375 // ABSL_ATTRIBUTE_STACK_ALIGN_FOR_OLD_LIBC 376 // 377 // Support for aligning the stack on 32-bit x86. 378 #if ABSL_HAVE_ATTRIBUTE(force_align_arg_pointer) || \ 379 (defined(__GNUC__) && !defined(__clang__)) 380 #if defined(__i386__) 381 #define ABSL_ATTRIBUTE_STACK_ALIGN_FOR_OLD_LIBC \ 382 __attribute__((force_align_arg_pointer)) 383 #define ABSL_REQUIRE_STACK_ALIGN_TRAMPOLINE (0) 384 #elif defined(__x86_64__) 385 #define ABSL_REQUIRE_STACK_ALIGN_TRAMPOLINE (1) 386 #define ABSL_ATTRIBUTE_STACK_ALIGN_FOR_OLD_LIBC 387 #else // !__i386__ && !__x86_64 388 #define ABSL_REQUIRE_STACK_ALIGN_TRAMPOLINE (0) 389 #define ABSL_ATTRIBUTE_STACK_ALIGN_FOR_OLD_LIBC 390 #endif // __i386__ 391 #else 392 #define ABSL_ATTRIBUTE_STACK_ALIGN_FOR_OLD_LIBC 393 #define ABSL_REQUIRE_STACK_ALIGN_TRAMPOLINE (0) 394 #endif 395 396 // ABSL_MUST_USE_RESULT 397 // 398 // Tells the compiler to warn about unused results. 399 // 400 // When annotating a function, it must appear as the first part of the 401 // declaration or definition. The compiler will warn if the return value from 402 // such a function is unused: 403 // 404 // ABSL_MUST_USE_RESULT Sprocket* AllocateSprocket(); 405 // AllocateSprocket(); // Triggers a warning. 406 // 407 // When annotating a class, it is equivalent to annotating every function which 408 // returns an instance. 409 // 410 // class ABSL_MUST_USE_RESULT Sprocket {}; 411 // Sprocket(); // Triggers a warning. 412 // 413 // Sprocket MakeSprocket(); 414 // MakeSprocket(); // Triggers a warning. 415 // 416 // Note that references and pointers are not instances: 417 // 418 // Sprocket* SprocketPointer(); 419 // SprocketPointer(); // Does *not* trigger a warning. 420 // 421 // ABSL_MUST_USE_RESULT allows using cast-to-void to suppress the unused result 422 // warning. For that, warn_unused_result is used only for clang but not for gcc. 423 // https://gcc.gnu.org/bugzilla/show_bug.cgi?id=66425 424 // 425 // Note: past advice was to place the macro after the argument list. 426 #if ABSL_HAVE_ATTRIBUTE(nodiscard) 427 #define ABSL_MUST_USE_RESULT [[nodiscard]] 428 #elif defined(__clang__) && ABSL_HAVE_ATTRIBUTE(warn_unused_result) 429 #define ABSL_MUST_USE_RESULT __attribute__((warn_unused_result)) 430 #else 431 #define ABSL_MUST_USE_RESULT 432 #endif 433 434 // ABSL_ATTRIBUTE_HOT, ABSL_ATTRIBUTE_COLD 435 // 436 // Tells GCC that a function is hot or cold. GCC can use this information to 437 // improve static analysis, i.e. a conditional branch to a cold function 438 // is likely to be not-taken. 439 // This annotation is used for function declarations. 440 // 441 // Example: 442 // 443 // int foo() ABSL_ATTRIBUTE_HOT; 444 #if ABSL_HAVE_ATTRIBUTE(hot) || (defined(__GNUC__) && !defined(__clang__)) 445 #define ABSL_ATTRIBUTE_HOT __attribute__((hot)) 446 #else 447 #define ABSL_ATTRIBUTE_HOT 448 #endif 449 450 #if ABSL_HAVE_ATTRIBUTE(cold) || (defined(__GNUC__) && !defined(__clang__)) 451 #define ABSL_ATTRIBUTE_COLD __attribute__((cold)) 452 #else 453 #define ABSL_ATTRIBUTE_COLD 454 #endif 455 456 // ABSL_XRAY_ALWAYS_INSTRUMENT, ABSL_XRAY_NEVER_INSTRUMENT, ABSL_XRAY_LOG_ARGS 457 // 458 // We define the ABSL_XRAY_ALWAYS_INSTRUMENT and ABSL_XRAY_NEVER_INSTRUMENT 459 // macro used as an attribute to mark functions that must always or never be 460 // instrumented by XRay. Currently, this is only supported in Clang/LLVM. 461 // 462 // For reference on the LLVM XRay instrumentation, see 463 // http://llvm.org/docs/XRay.html. 464 // 465 // A function with the XRAY_ALWAYS_INSTRUMENT macro attribute in its declaration 466 // will always get the XRay instrumentation sleds. These sleds may introduce 467 // some binary size and runtime overhead and must be used sparingly. 468 // 469 // These attributes only take effect when the following conditions are met: 470 // 471 // * The file/target is built in at least C++11 mode, with a Clang compiler 472 // that supports XRay attributes. 473 // * The file/target is built with the -fxray-instrument flag set for the 474 // Clang/LLVM compiler. 475 // * The function is defined in the translation unit (the compiler honors the 476 // attribute in either the definition or the declaration, and must match). 477 // 478 // There are cases when, even when building with XRay instrumentation, users 479 // might want to control specifically which functions are instrumented for a 480 // particular build using special-case lists provided to the compiler. These 481 // special case lists are provided to Clang via the 482 // -fxray-always-instrument=... and -fxray-never-instrument=... flags. The 483 // attributes in source take precedence over these special-case lists. 484 // 485 // To disable the XRay attributes at build-time, users may define 486 // ABSL_NO_XRAY_ATTRIBUTES. Do NOT define ABSL_NO_XRAY_ATTRIBUTES on specific 487 // packages/targets, as this may lead to conflicting definitions of functions at 488 // link-time. 489 // 490 // XRay isn't currently supported on Android: 491 // https://github.com/android/ndk/issues/368 492 #if ABSL_HAVE_CPP_ATTRIBUTE(clang::xray_always_instrument) && \ 493 !defined(ABSL_NO_XRAY_ATTRIBUTES) && !defined(__ANDROID__) 494 #define ABSL_XRAY_ALWAYS_INSTRUMENT [[clang::xray_always_instrument]] 495 #define ABSL_XRAY_NEVER_INSTRUMENT [[clang::xray_never_instrument]] 496 #if ABSL_HAVE_CPP_ATTRIBUTE(clang::xray_log_args) 497 #define ABSL_XRAY_LOG_ARGS(N) \ 498 [[clang::xray_always_instrument, clang::xray_log_args(N)]] 499 #else 500 #define ABSL_XRAY_LOG_ARGS(N) [[clang::xray_always_instrument]] 501 #endif 502 #else 503 #define ABSL_XRAY_ALWAYS_INSTRUMENT 504 #define ABSL_XRAY_NEVER_INSTRUMENT 505 #define ABSL_XRAY_LOG_ARGS(N) 506 #endif 507 508 // ABSL_ATTRIBUTE_REINITIALIZES 509 // 510 // Indicates that a member function reinitializes the entire object to a known 511 // state, independent of the previous state of the object. 512 // 513 // The clang-tidy check bugprone-use-after-move allows member functions marked 514 // with this attribute to be called on objects that have been moved from; 515 // without the attribute, this would result in a use-after-move warning. 516 #if ABSL_HAVE_CPP_ATTRIBUTE(clang::reinitializes) 517 #define ABSL_ATTRIBUTE_REINITIALIZES [[clang::reinitializes]] 518 #else 519 #define ABSL_ATTRIBUTE_REINITIALIZES 520 #endif 521 522 // ----------------------------------------------------------------------------- 523 // Variable Attributes 524 // ----------------------------------------------------------------------------- 525 526 // ABSL_ATTRIBUTE_UNUSED 527 // 528 // Prevents the compiler from complaining about variables that appear unused. 529 #if ABSL_HAVE_ATTRIBUTE(unused) || (defined(__GNUC__) && !defined(__clang__)) 530 #undef ABSL_ATTRIBUTE_UNUSED 531 #define ABSL_ATTRIBUTE_UNUSED __attribute__((__unused__)) 532 #else 533 #define ABSL_ATTRIBUTE_UNUSED 534 #endif 535 536 // ABSL_ATTRIBUTE_INITIAL_EXEC 537 // 538 // Tells the compiler to use "initial-exec" mode for a thread-local variable. 539 // See http://people.redhat.com/drepper/tls.pdf for the gory details. 540 #if ABSL_HAVE_ATTRIBUTE(tls_model) || (defined(__GNUC__) && !defined(__clang__)) 541 #define ABSL_ATTRIBUTE_INITIAL_EXEC __attribute__((tls_model("initial-exec"))) 542 #else 543 #define ABSL_ATTRIBUTE_INITIAL_EXEC 544 #endif 545 546 // ABSL_ATTRIBUTE_PACKED 547 // 548 // Instructs the compiler not to use natural alignment for a tagged data 549 // structure, but instead to reduce its alignment to 1. This attribute can 550 // either be applied to members of a structure or to a structure in its 551 // entirety. Applying this attribute (judiciously) to a structure in its 552 // entirety to optimize the memory footprint of very commonly-used structs is 553 // fine. Do not apply this attribute to a structure in its entirety if the 554 // purpose is to control the offsets of the members in the structure. Instead, 555 // apply this attribute only to structure members that need it. 556 // 557 // When applying ABSL_ATTRIBUTE_PACKED only to specific structure members the 558 // natural alignment of structure members not annotated is preserved. Aligned 559 // member accesses are faster than non-aligned member accesses even if the 560 // targeted microprocessor supports non-aligned accesses. 561 #if ABSL_HAVE_ATTRIBUTE(packed) || (defined(__GNUC__) && !defined(__clang__)) 562 #define ABSL_ATTRIBUTE_PACKED __attribute__((__packed__)) 563 #else 564 #define ABSL_ATTRIBUTE_PACKED 565 #endif 566 567 // ABSL_ATTRIBUTE_FUNC_ALIGN 568 // 569 // Tells the compiler to align the function start at least to certain 570 // alignment boundary 571 #if ABSL_HAVE_ATTRIBUTE(aligned) || (defined(__GNUC__) && !defined(__clang__)) 572 #define ABSL_ATTRIBUTE_FUNC_ALIGN(bytes) __attribute__((aligned(bytes))) 573 #else 574 #define ABSL_ATTRIBUTE_FUNC_ALIGN(bytes) 575 #endif 576 577 // ABSL_FALLTHROUGH_INTENDED 578 // 579 // Annotates implicit fall-through between switch labels, allowing a case to 580 // indicate intentional fallthrough and turn off warnings about any lack of a 581 // `break` statement. The ABSL_FALLTHROUGH_INTENDED macro should be followed by 582 // a semicolon and can be used in most places where `break` can, provided that 583 // no statements exist between it and the next switch label. 584 // 585 // Example: 586 // 587 // switch (x) { 588 // case 40: 589 // case 41: 590 // if (truth_is_out_there) { 591 // ++x; 592 // ABSL_FALLTHROUGH_INTENDED; // Use instead of/along with annotations 593 // // in comments 594 // } else { 595 // return x; 596 // } 597 // case 42: 598 // ... 599 // 600 // Notes: when compiled with clang in C++11 mode, the ABSL_FALLTHROUGH_INTENDED 601 // macro is expanded to the [[clang::fallthrough]] attribute, which is analysed 602 // when performing switch labels fall-through diagnostic 603 // (`-Wimplicit-fallthrough`). See clang documentation on language extensions 604 // for details: 605 // https://clang.llvm.org/docs/AttributeReference.html#fallthrough-clang-fallthrough 606 // 607 // When used with unsupported compilers, the ABSL_FALLTHROUGH_INTENDED macro 608 // has no effect on diagnostics. In any case this macro has no effect on runtime 609 // behavior and performance of code. 610 #ifdef ABSL_FALLTHROUGH_INTENDED 611 #error "ABSL_FALLTHROUGH_INTENDED should not be defined." 612 #endif 613 614 // TODO(zhangxy): Use c++17 standard [[fallthrough]] macro, when supported. 615 #if defined(__clang__) && defined(__has_warning) 616 #if __has_feature(cxx_attributes) && __has_warning("-Wimplicit-fallthrough") 617 #define ABSL_FALLTHROUGH_INTENDED [[clang::fallthrough]] 618 #endif 619 #elif defined(__GNUC__) && __GNUC__ >= 7 620 #define ABSL_FALLTHROUGH_INTENDED [[gnu::fallthrough]] 621 #endif 622 623 #ifndef ABSL_FALLTHROUGH_INTENDED 624 #define ABSL_FALLTHROUGH_INTENDED \ 625 do { \ 626 } while (0) 627 #endif 628 629 // ABSL_DEPRECATED() 630 // 631 // Marks a deprecated class, struct, enum, function, method and variable 632 // declarations. The macro argument is used as a custom diagnostic message (e.g. 633 // suggestion of a better alternative). 634 // 635 // Examples: 636 // 637 // class ABSL_DEPRECATED("Use Bar instead") Foo {...}; 638 // 639 // ABSL_DEPRECATED("Use Baz() instead") void Bar() {...} 640 // 641 // template <typename T> 642 // ABSL_DEPRECATED("Use DoThat() instead") 643 // void DoThis(); 644 // 645 // Every usage of a deprecated entity will trigger a warning when compiled with 646 // clang's `-Wdeprecated-declarations` option. This option is turned off by 647 // default, but the warnings will be reported by clang-tidy. 648 #if defined(__clang__) && __cplusplus >= 201103L 649 #define ABSL_DEPRECATED(message) __attribute__((deprecated(message))) 650 #endif 651 652 #ifndef ABSL_DEPRECATED 653 #define ABSL_DEPRECATED(message) 654 #endif 655 656 // ABSL_CONST_INIT 657 // 658 // A variable declaration annotated with the `ABSL_CONST_INIT` attribute will 659 // not compile (on supported platforms) unless the variable has a constant 660 // initializer. This is useful for variables with static and thread storage 661 // duration, because it guarantees that they will not suffer from the so-called 662 // "static init order fiasco". Prefer to put this attribute on the most visible 663 // declaration of the variable, if there's more than one, because code that 664 // accesses the variable can then use the attribute for optimization. 665 // 666 // Example: 667 // 668 // class MyClass { 669 // public: 670 // ABSL_CONST_INIT static MyType my_var; 671 // }; 672 // 673 // MyType MyClass::my_var = MakeMyType(...); 674 // 675 // Note that this attribute is redundant if the variable is declared constexpr. 676 #if ABSL_HAVE_CPP_ATTRIBUTE(clang::require_constant_initialization) 677 #define ABSL_CONST_INIT [[clang::require_constant_initialization]] 678 #else 679 #define ABSL_CONST_INIT 680 #endif // ABSL_HAVE_CPP_ATTRIBUTE(clang::require_constant_initialization) 681 682 #endif // ABSL_BASE_ATTRIBUTES_H_ 683