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