attributes.h (43140B)
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 // SKIP_ABSL_INLINE_NAMESPACE_CHECK 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__) && !defined(__e2k__) 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 did not work properly in LLVM's Windows backend before 137 // 9.0.0, so disable them there. See https://bugs.llvm.org/show_bug.cgi?id=37598 138 // for further information. Weak attributes do not work across DLL boundary. 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(_WIN32) || \ 144 (defined(__clang__) && __clang_major__ >= 9 && \ 145 !defined(ABSL_BUILD_DLL) && !defined(ABSL_CONSUME_DLL))) && \ 146 !defined(__MINGW32__) 147 #undef ABSL_ATTRIBUTE_WEAK 148 #define ABSL_ATTRIBUTE_WEAK __attribute__((weak)) 149 #define ABSL_HAVE_ATTRIBUTE_WEAK 1 150 #else 151 #define ABSL_ATTRIBUTE_WEAK 152 #define ABSL_HAVE_ATTRIBUTE_WEAK 0 153 #endif 154 155 // ABSL_ATTRIBUTE_NONNULL 156 // 157 // Tells the compiler either (a) that a particular function parameter 158 // should be a non-null pointer, or (b) that all pointer arguments should 159 // be non-null. 160 // 161 // Note: As the GCC manual states, "[s]ince non-static C++ methods 162 // have an implicit 'this' argument, the arguments of such methods 163 // should be counted from two, not one." 164 // 165 // Args are indexed starting at 1. 166 // 167 // For non-static class member functions, the implicit `this` argument 168 // is arg 1, and the first explicit argument is arg 2. For static class member 169 // functions, there is no implicit `this`, and the first explicit argument is 170 // arg 1. 171 // 172 // Example: 173 // 174 // /* arg_a cannot be null, but arg_b can */ 175 // void Function(void* arg_a, void* arg_b) ABSL_ATTRIBUTE_NONNULL(1); 176 // 177 // class C { 178 // /* arg_a cannot be null, but arg_b can */ 179 // void Method(void* arg_a, void* arg_b) ABSL_ATTRIBUTE_NONNULL(2); 180 // 181 // /* arg_a cannot be null, but arg_b can */ 182 // static void StaticMethod(void* arg_a, void* arg_b) 183 // ABSL_ATTRIBUTE_NONNULL(1); 184 // }; 185 // 186 // If no arguments are provided, then all pointer arguments should be non-null. 187 // 188 // /* No pointer arguments may be null. */ 189 // void Function(void* arg_a, void* arg_b, int arg_c) ABSL_ATTRIBUTE_NONNULL(); 190 // 191 // NOTE: The GCC nonnull attribute actually accepts a list of arguments, but 192 // ABSL_ATTRIBUTE_NONNULL does not. 193 #if ABSL_HAVE_ATTRIBUTE(nonnull) || (defined(__GNUC__) && !defined(__clang__)) 194 #define ABSL_ATTRIBUTE_NONNULL(arg_index) __attribute__((nonnull(arg_index))) 195 #else 196 #define ABSL_ATTRIBUTE_NONNULL(...) 197 #endif 198 199 // ABSL_ATTRIBUTE_NORETURN 200 // 201 // Tells the compiler that a given function never returns. 202 // 203 // Deprecated: Prefer the `[[noreturn]]` attribute standardized by C++11 over 204 // this macro. 205 #if ABSL_HAVE_ATTRIBUTE(noreturn) || (defined(__GNUC__) && !defined(__clang__)) 206 #define ABSL_ATTRIBUTE_NORETURN __attribute__((noreturn)) 207 #elif defined(_MSC_VER) 208 #define ABSL_ATTRIBUTE_NORETURN __declspec(noreturn) 209 #else 210 #define ABSL_ATTRIBUTE_NORETURN 211 #endif 212 213 // ABSL_ATTRIBUTE_NO_SANITIZE_ADDRESS 214 // 215 // Tells the AddressSanitizer (or other memory testing tools) to ignore a given 216 // function. Useful for cases when a function reads random locations on stack, 217 // calls _exit from a cloned subprocess, deliberately accesses buffer 218 // out of bounds or does other scary things with memory. 219 // NOTE: GCC supports AddressSanitizer(asan) since 4.8. 220 // https://gcc.gnu.org/gcc-4.8/changes.html 221 #if defined(ABSL_HAVE_ADDRESS_SANITIZER) && \ 222 ABSL_HAVE_ATTRIBUTE(no_sanitize_address) 223 #define ABSL_ATTRIBUTE_NO_SANITIZE_ADDRESS __attribute__((no_sanitize_address)) 224 #elif defined(ABSL_HAVE_ADDRESS_SANITIZER) && defined(_MSC_VER) && \ 225 _MSC_VER >= 1928 226 // https://docs.microsoft.com/en-us/cpp/cpp/no-sanitize-address 227 #define ABSL_ATTRIBUTE_NO_SANITIZE_ADDRESS __declspec(no_sanitize_address) 228 #elif defined(ABSL_HAVE_HWADDRESS_SANITIZER) && ABSL_HAVE_ATTRIBUTE(no_sanitize) 229 // HWAddressSanitizer is a sanitizer similar to AddressSanitizer, which uses CPU 230 // features to detect similar bugs with less CPU and memory overhead. 231 // NOTE: GCC supports HWAddressSanitizer(hwasan) since 11. 232 // https://gcc.gnu.org/gcc-11/changes.html 233 #define ABSL_ATTRIBUTE_NO_SANITIZE_ADDRESS \ 234 __attribute__((no_sanitize("hwaddress"))) 235 #else 236 #define ABSL_ATTRIBUTE_NO_SANITIZE_ADDRESS 237 #endif 238 239 // ABSL_ATTRIBUTE_NO_SANITIZE_MEMORY 240 // 241 // Tells the MemorySanitizer to relax the handling of a given function. All "Use 242 // of uninitialized value" warnings from such functions will be suppressed, and 243 // all values loaded from memory will be considered fully initialized. This 244 // attribute is similar to the ABSL_ATTRIBUTE_NO_SANITIZE_ADDRESS attribute 245 // above, but deals with initialized-ness rather than addressability issues. 246 // NOTE: MemorySanitizer(msan) is supported by Clang but not GCC. 247 #if ABSL_HAVE_ATTRIBUTE(no_sanitize_memory) 248 #define ABSL_ATTRIBUTE_NO_SANITIZE_MEMORY __attribute__((no_sanitize_memory)) 249 #else 250 #define ABSL_ATTRIBUTE_NO_SANITIZE_MEMORY 251 #endif 252 253 // ABSL_ATTRIBUTE_NO_SANITIZE_THREAD 254 // 255 // Tells the ThreadSanitizer to not instrument a given function. 256 // NOTE: GCC supports ThreadSanitizer(tsan) since 4.8. 257 // https://gcc.gnu.org/gcc-4.8/changes.html 258 #if ABSL_HAVE_ATTRIBUTE(no_sanitize_thread) 259 #define ABSL_ATTRIBUTE_NO_SANITIZE_THREAD __attribute__((no_sanitize_thread)) 260 #else 261 #define ABSL_ATTRIBUTE_NO_SANITIZE_THREAD 262 #endif 263 264 // ABSL_ATTRIBUTE_NO_SANITIZE_UNDEFINED 265 // 266 // Tells the UndefinedSanitizer to ignore a given function. Useful for cases 267 // where certain behavior (eg. division by zero) is being used intentionally. 268 // NOTE: GCC supports UndefinedBehaviorSanitizer(ubsan) since 4.9. 269 // https://gcc.gnu.org/gcc-4.9/changes.html 270 #if ABSL_HAVE_ATTRIBUTE(no_sanitize_undefined) 271 #define ABSL_ATTRIBUTE_NO_SANITIZE_UNDEFINED \ 272 __attribute__((no_sanitize_undefined)) 273 #elif ABSL_HAVE_ATTRIBUTE(no_sanitize) 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 ABSL_HAVE_ATTRIBUTE(no_sanitize) && defined(__llvm__) 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 ABSL_HAVE_ATTRIBUTE(no_sanitize) 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 #define ABSL_ATTRIBUTE_RETURNS_NONNULL __attribute__((returns_nonnull)) 306 #else 307 #define ABSL_ATTRIBUTE_RETURNS_NONNULL 308 #endif 309 310 // ABSL_HAVE_ATTRIBUTE_SECTION 311 // 312 // Indicates whether labeled sections are supported. Weak symbol support is 313 // a prerequisite. Labeled sections are not supported on Darwin/iOS. 314 #ifdef ABSL_HAVE_ATTRIBUTE_SECTION 315 #error ABSL_HAVE_ATTRIBUTE_SECTION cannot be directly set 316 #elif (ABSL_HAVE_ATTRIBUTE(section) || \ 317 (defined(__GNUC__) && !defined(__clang__))) && \ 318 !defined(__APPLE__) && ABSL_HAVE_ATTRIBUTE_WEAK 319 #define ABSL_HAVE_ATTRIBUTE_SECTION 1 320 321 // ABSL_ATTRIBUTE_SECTION 322 // 323 // Tells the compiler/linker to put a given function into a section and define 324 // `__start_ ## name` and `__stop_ ## name` symbols to bracket the section. 325 // This functionality is supported by GNU linker. Any function annotated with 326 // `ABSL_ATTRIBUTE_SECTION` must not be inlined, or it will be placed into 327 // whatever section its caller is placed into. 328 // 329 #ifndef ABSL_ATTRIBUTE_SECTION 330 #define ABSL_ATTRIBUTE_SECTION(name) \ 331 __attribute__((section(#name))) __attribute__((noinline)) 332 #endif 333 334 // ABSL_ATTRIBUTE_SECTION_VARIABLE 335 // 336 // Tells the compiler/linker to put a given variable into a section and define 337 // `__start_ ## name` and `__stop_ ## name` symbols to bracket the section. 338 // This functionality is supported by GNU linker. 339 #ifndef ABSL_ATTRIBUTE_SECTION_VARIABLE 340 #ifdef _AIX 341 // __attribute__((section(#name))) on AIX is achieved by using the `.csect` 342 // psudo op which includes an additional integer as part of its syntax indcating 343 // alignment. If data fall under different alignments then you might get a 344 // compilation error indicating a `Section type conflict`. 345 #define ABSL_ATTRIBUTE_SECTION_VARIABLE(name) 346 #else 347 #define ABSL_ATTRIBUTE_SECTION_VARIABLE(name) __attribute__((section(#name))) 348 #endif 349 #endif 350 351 // ABSL_DECLARE_ATTRIBUTE_SECTION_VARS 352 // 353 // A weak section declaration to be used as a global declaration 354 // for ABSL_ATTRIBUTE_SECTION_START|STOP(name) to compile and link 355 // even without functions with ABSL_ATTRIBUTE_SECTION(name). 356 // ABSL_DEFINE_ATTRIBUTE_SECTION should be in the exactly one file; it's 357 // a no-op on ELF but not on Mach-O. 358 // 359 #ifndef ABSL_DECLARE_ATTRIBUTE_SECTION_VARS 360 #define ABSL_DECLARE_ATTRIBUTE_SECTION_VARS(name) \ 361 extern char __start_##name[] ABSL_ATTRIBUTE_WEAK; \ 362 extern char __stop_##name[] ABSL_ATTRIBUTE_WEAK 363 #endif 364 #ifndef ABSL_DEFINE_ATTRIBUTE_SECTION_VARS 365 #define ABSL_INIT_ATTRIBUTE_SECTION_VARS(name) 366 #define ABSL_DEFINE_ATTRIBUTE_SECTION_VARS(name) 367 #endif 368 369 // ABSL_ATTRIBUTE_SECTION_START 370 // 371 // Returns `void*` pointers to start/end of a section of code with 372 // functions having ABSL_ATTRIBUTE_SECTION(name). 373 // Returns 0 if no such functions exist. 374 // One must ABSL_DECLARE_ATTRIBUTE_SECTION_VARS(name) for this to compile and 375 // link. 376 // 377 #define ABSL_ATTRIBUTE_SECTION_START(name) \ 378 (reinterpret_cast<void *>(__start_##name)) 379 #define ABSL_ATTRIBUTE_SECTION_STOP(name) \ 380 (reinterpret_cast<void *>(__stop_##name)) 381 382 #else // !ABSL_HAVE_ATTRIBUTE_SECTION 383 384 #define ABSL_HAVE_ATTRIBUTE_SECTION 0 385 386 // provide dummy definitions 387 #define ABSL_ATTRIBUTE_SECTION(name) 388 #define ABSL_ATTRIBUTE_SECTION_VARIABLE(name) 389 #define ABSL_INIT_ATTRIBUTE_SECTION_VARS(name) 390 #define ABSL_DEFINE_ATTRIBUTE_SECTION_VARS(name) 391 #define ABSL_DECLARE_ATTRIBUTE_SECTION_VARS(name) 392 #define ABSL_ATTRIBUTE_SECTION_START(name) (reinterpret_cast<void *>(0)) 393 #define ABSL_ATTRIBUTE_SECTION_STOP(name) (reinterpret_cast<void *>(0)) 394 395 #endif // ABSL_ATTRIBUTE_SECTION 396 397 // ABSL_ATTRIBUTE_STACK_ALIGN_FOR_OLD_LIBC 398 // 399 // Support for aligning the stack on 32-bit x86. 400 #if ABSL_HAVE_ATTRIBUTE(force_align_arg_pointer) || \ 401 (defined(__GNUC__) && !defined(__clang__)) 402 #if defined(__i386__) 403 #define ABSL_ATTRIBUTE_STACK_ALIGN_FOR_OLD_LIBC \ 404 __attribute__((force_align_arg_pointer)) 405 #define ABSL_REQUIRE_STACK_ALIGN_TRAMPOLINE (0) 406 #elif defined(__x86_64__) 407 #define ABSL_REQUIRE_STACK_ALIGN_TRAMPOLINE (1) 408 #define ABSL_ATTRIBUTE_STACK_ALIGN_FOR_OLD_LIBC 409 #else // !__i386__ && !__x86_64 410 #define ABSL_REQUIRE_STACK_ALIGN_TRAMPOLINE (0) 411 #define ABSL_ATTRIBUTE_STACK_ALIGN_FOR_OLD_LIBC 412 #endif // __i386__ 413 #else 414 #define ABSL_ATTRIBUTE_STACK_ALIGN_FOR_OLD_LIBC 415 #define ABSL_REQUIRE_STACK_ALIGN_TRAMPOLINE (0) 416 #endif 417 418 // ABSL_MUST_USE_RESULT 419 // 420 // Tells the compiler to warn about unused results. 421 // 422 // For code or headers that are assured to only build with C++17 and up, prefer 423 // just using the standard `[[nodiscard]]` directly over this macro. 424 // 425 // When annotating a function, it must appear as the first part of the 426 // declaration or definition. The compiler will warn if the return value from 427 // such a function is unused: 428 // 429 // ABSL_MUST_USE_RESULT Sprocket* AllocateSprocket(); 430 // AllocateSprocket(); // Triggers a warning. 431 // 432 // When annotating a class, it is equivalent to annotating every function which 433 // returns an instance. 434 // 435 // class ABSL_MUST_USE_RESULT Sprocket {}; 436 // Sprocket(); // Triggers a warning. 437 // 438 // Sprocket MakeSprocket(); 439 // MakeSprocket(); // Triggers a warning. 440 // 441 // Note that references and pointers are not instances: 442 // 443 // Sprocket* SprocketPointer(); 444 // SprocketPointer(); // Does *not* trigger a warning. 445 // 446 // ABSL_MUST_USE_RESULT allows using cast-to-void to suppress the unused result 447 // warning. For that, warn_unused_result is used only for clang but not for gcc. 448 // https://gcc.gnu.org/bugzilla/show_bug.cgi?id=66425 449 // 450 // Note: past advice was to place the macro after the argument list. 451 // 452 // TODO(b/176172494): Use ABSL_HAVE_CPP_ATTRIBUTE(nodiscard) when all code is 453 // compliant with the stricter [[nodiscard]]. 454 #if defined(__clang__) && ABSL_HAVE_ATTRIBUTE(warn_unused_result) 455 #define ABSL_MUST_USE_RESULT __attribute__((warn_unused_result)) 456 #else 457 #define ABSL_MUST_USE_RESULT 458 #endif 459 460 // ABSL_ATTRIBUTE_HOT, ABSL_ATTRIBUTE_COLD 461 // 462 // Tells GCC that a function is hot or cold. GCC can use this information to 463 // improve static analysis, i.e. a conditional branch to a cold function 464 // is likely to be not-taken. 465 // This annotation is used for function declarations. 466 // 467 // Example: 468 // 469 // int foo() ABSL_ATTRIBUTE_HOT; 470 #if ABSL_HAVE_ATTRIBUTE(hot) || (defined(__GNUC__) && !defined(__clang__)) 471 #define ABSL_ATTRIBUTE_HOT __attribute__((hot)) 472 #else 473 #define ABSL_ATTRIBUTE_HOT 474 #endif 475 476 #if ABSL_HAVE_ATTRIBUTE(cold) || (defined(__GNUC__) && !defined(__clang__)) 477 #define ABSL_ATTRIBUTE_COLD __attribute__((cold)) 478 #else 479 #define ABSL_ATTRIBUTE_COLD 480 #endif 481 482 // ABSL_XRAY_ALWAYS_INSTRUMENT, ABSL_XRAY_NEVER_INSTRUMENT, ABSL_XRAY_LOG_ARGS 483 // 484 // We define the ABSL_XRAY_ALWAYS_INSTRUMENT and ABSL_XRAY_NEVER_INSTRUMENT 485 // macro used as an attribute to mark functions that must always or never be 486 // instrumented by XRay. Currently, this is only supported in Clang/LLVM. 487 // 488 // For reference on the LLVM XRay instrumentation, see 489 // http://llvm.org/docs/XRay.html. 490 // 491 // A function with the XRAY_ALWAYS_INSTRUMENT macro attribute in its declaration 492 // will always get the XRay instrumentation sleds. These sleds may introduce 493 // some binary size and runtime overhead and must be used sparingly. 494 // 495 // These attributes only take effect when the following conditions are met: 496 // 497 // * The file/target is built in at least C++11 mode, with a Clang compiler 498 // that supports XRay attributes. 499 // * The file/target is built with the -fxray-instrument flag set for the 500 // Clang/LLVM compiler. 501 // * The function is defined in the translation unit (the compiler honors the 502 // attribute in either the definition or the declaration, and must match). 503 // 504 // There are cases when, even when building with XRay instrumentation, users 505 // might want to control specifically which functions are instrumented for a 506 // particular build using special-case lists provided to the compiler. These 507 // special case lists are provided to Clang via the 508 // -fxray-always-instrument=... and -fxray-never-instrument=... flags. The 509 // attributes in source take precedence over these special-case lists. 510 // 511 // To disable the XRay attributes at build-time, users may define 512 // ABSL_NO_XRAY_ATTRIBUTES. Do NOT define ABSL_NO_XRAY_ATTRIBUTES on specific 513 // packages/targets, as this may lead to conflicting definitions of functions at 514 // link-time. 515 // 516 // XRay isn't currently supported on Android: 517 // https://github.com/android/ndk/issues/368 518 #if ABSL_HAVE_CPP_ATTRIBUTE(clang::xray_always_instrument) && \ 519 !defined(ABSL_NO_XRAY_ATTRIBUTES) && !defined(__ANDROID__) 520 #define ABSL_XRAY_ALWAYS_INSTRUMENT [[clang::xray_always_instrument]] 521 #define ABSL_XRAY_NEVER_INSTRUMENT [[clang::xray_never_instrument]] 522 #if ABSL_HAVE_CPP_ATTRIBUTE(clang::xray_log_args) 523 #define ABSL_XRAY_LOG_ARGS(N) \ 524 [[clang::xray_always_instrument, clang::xray_log_args(N)]] 525 #else 526 #define ABSL_XRAY_LOG_ARGS(N) [[clang::xray_always_instrument]] 527 #endif 528 #else 529 #define ABSL_XRAY_ALWAYS_INSTRUMENT 530 #define ABSL_XRAY_NEVER_INSTRUMENT 531 #define ABSL_XRAY_LOG_ARGS(N) 532 #endif 533 534 // ABSL_ATTRIBUTE_REINITIALIZES 535 // 536 // Indicates that a member function reinitializes the entire object to a known 537 // state, independent of the previous state of the object. 538 // 539 // The clang-tidy check bugprone-use-after-move allows member functions marked 540 // with this attribute to be called on objects that have been moved from; 541 // without the attribute, this would result in a use-after-move warning. 542 #if ABSL_HAVE_CPP_ATTRIBUTE(clang::reinitializes) 543 #define ABSL_ATTRIBUTE_REINITIALIZES [[clang::reinitializes]] 544 #else 545 #define ABSL_ATTRIBUTE_REINITIALIZES 546 #endif 547 548 // ----------------------------------------------------------------------------- 549 // Variable Attributes 550 // ----------------------------------------------------------------------------- 551 552 // ABSL_ATTRIBUTE_UNUSED 553 // 554 // Prevents the compiler from complaining about variables that appear unused. 555 // 556 // Deprecated: Use the standard C++17 `[[maybe_unused]` instead. 557 // 558 // Due to differences in positioning requirements between the old, compiler 559 // specific __attribute__ syntax and the now standard `[[maybe_unused]]`, this 560 // macro does not attempt to take advantage of `[[maybe_unused]]`. 561 #if ABSL_HAVE_ATTRIBUTE(unused) || (defined(__GNUC__) && !defined(__clang__)) 562 #undef ABSL_ATTRIBUTE_UNUSED 563 #define ABSL_ATTRIBUTE_UNUSED __attribute__((__unused__)) 564 #else 565 #define ABSL_ATTRIBUTE_UNUSED 566 #endif 567 568 // ABSL_ATTRIBUTE_INITIAL_EXEC 569 // 570 // Tells the compiler to use "initial-exec" mode for a thread-local variable. 571 // See http://people.redhat.com/drepper/tls.pdf for the gory details. 572 #if ABSL_HAVE_ATTRIBUTE(tls_model) || (defined(__GNUC__) && !defined(__clang__)) 573 #define ABSL_ATTRIBUTE_INITIAL_EXEC __attribute__((tls_model("initial-exec"))) 574 #else 575 #define ABSL_ATTRIBUTE_INITIAL_EXEC 576 #endif 577 578 // ABSL_ATTRIBUTE_PACKED 579 // 580 // Instructs the compiler not to use natural alignment for a tagged data 581 // structure, but instead to reduce its alignment to 1. 582 // 583 // Therefore, DO NOT APPLY THIS ATTRIBUTE TO STRUCTS CONTAINING ATOMICS. Doing 584 // so can cause atomic variables to be mis-aligned and silently violate 585 // atomicity on x86. 586 // 587 // This attribute can either be applied to members of a structure or to a 588 // structure in its entirety. Applying this attribute (judiciously) to a 589 // structure in its entirety to optimize the memory footprint of very 590 // commonly-used structs is fine. Do not apply this attribute to a structure in 591 // its entirety if the purpose is to control the offsets of the members in the 592 // structure. Instead, apply this attribute only to structure members that need 593 // it. 594 // 595 // When applying ABSL_ATTRIBUTE_PACKED only to specific structure members the 596 // natural alignment of structure members not annotated is preserved. Aligned 597 // member accesses are faster than non-aligned member accesses even if the 598 // targeted microprocessor supports non-aligned accesses. 599 #if ABSL_HAVE_ATTRIBUTE(packed) || (defined(__GNUC__) && !defined(__clang__)) 600 #define ABSL_ATTRIBUTE_PACKED __attribute__((__packed__)) 601 #else 602 #define ABSL_ATTRIBUTE_PACKED 603 #endif 604 605 // ABSL_ATTRIBUTE_FUNC_ALIGN 606 // 607 // Tells the compiler to align the function start at least to certain 608 // alignment boundary 609 #if ABSL_HAVE_ATTRIBUTE(aligned) || (defined(__GNUC__) && !defined(__clang__)) 610 #define ABSL_ATTRIBUTE_FUNC_ALIGN(bytes) __attribute__((aligned(bytes))) 611 #else 612 #define ABSL_ATTRIBUTE_FUNC_ALIGN(bytes) 613 #endif 614 615 // ABSL_FALLTHROUGH_INTENDED 616 // 617 // Annotates implicit fall-through between switch labels, allowing a case to 618 // indicate intentional fallthrough and turn off warnings about any lack of a 619 // `break` statement. The ABSL_FALLTHROUGH_INTENDED macro should be followed by 620 // a semicolon and can be used in most places where `break` can, provided that 621 // no statements exist between it and the next switch label. 622 // 623 // Example: 624 // 625 // switch (x) { 626 // case 40: 627 // case 41: 628 // if (truth_is_out_there) { 629 // ++x; 630 // ABSL_FALLTHROUGH_INTENDED; // Use instead of/along with annotations 631 // // in comments 632 // } else { 633 // return x; 634 // } 635 // case 42: 636 // ... 637 // 638 // Notes: When supported, GCC and Clang can issue a warning on switch labels 639 // with unannotated fallthrough using the warning `-Wimplicit-fallthrough`. See 640 // clang documentation on language extensions for details: 641 // https://clang.llvm.org/docs/AttributeReference.html#fallthrough-clang-fallthrough 642 // 643 // When used with unsupported compilers, the ABSL_FALLTHROUGH_INTENDED macro has 644 // no effect on diagnostics. In any case this macro has no effect on runtime 645 // behavior and performance of code. 646 647 #ifdef ABSL_FALLTHROUGH_INTENDED 648 #error "ABSL_FALLTHROUGH_INTENDED should not be defined." 649 #elif ABSL_HAVE_CPP_ATTRIBUTE(fallthrough) 650 #define ABSL_FALLTHROUGH_INTENDED [[fallthrough]] 651 #elif ABSL_HAVE_CPP_ATTRIBUTE(clang::fallthrough) 652 #define ABSL_FALLTHROUGH_INTENDED [[clang::fallthrough]] 653 #elif ABSL_HAVE_CPP_ATTRIBUTE(gnu::fallthrough) 654 #define ABSL_FALLTHROUGH_INTENDED [[gnu::fallthrough]] 655 #else 656 #define ABSL_FALLTHROUGH_INTENDED \ 657 do { \ 658 } while (0) 659 #endif 660 661 // ABSL_DEPRECATED() 662 // 663 // Marks a deprecated class, struct, enum, function, method and variable 664 // declarations. The macro argument is used as a custom diagnostic message (e.g. 665 // suggestion of a better alternative). 666 // 667 // For code or headers that are assured to only build with C++14 and up, prefer 668 // just using the standard `[[deprecated("message")]]` directly over this macro. 669 // 670 // Examples: 671 // 672 // class ABSL_DEPRECATED("Use Bar instead") Foo {...}; 673 // 674 // ABSL_DEPRECATED("Use Baz() instead") void Bar() {...} 675 // 676 // template <typename T> 677 // ABSL_DEPRECATED("Use DoThat() instead") 678 // void DoThis(); 679 // 680 // enum FooEnum { 681 // kBar ABSL_DEPRECATED("Use kBaz instead"), 682 // }; 683 // 684 // Every usage of a deprecated entity will trigger a warning when compiled with 685 // GCC/Clang's `-Wdeprecated-declarations` option. Google's production toolchain 686 // turns this warning off by default, instead relying on clang-tidy to report 687 // new uses of deprecated code. 688 #if ABSL_HAVE_ATTRIBUTE(deprecated) 689 #define ABSL_DEPRECATED(message) __attribute__((deprecated(message))) 690 #else 691 #define ABSL_DEPRECATED(message) 692 #endif 693 694 // When deprecating Abseil code, it is sometimes necessary to turn off the 695 // warning within Abseil, until the deprecated code is actually removed. The 696 // deprecated code can be surrounded with these directives to achieve that 697 // result. 698 // 699 // class ABSL_DEPRECATED("Use Bar instead") Foo; 700 // 701 // ABSL_INTERNAL_DISABLE_DEPRECATED_DECLARATION_WARNING 702 // Baz ComputeBazFromFoo(Foo f); 703 // ABSL_INTERNAL_RESTORE_DEPRECATED_DECLARATION_WARNING 704 #if defined(__GNUC__) || defined(__clang__) 705 // Clang also supports these GCC pragmas. 706 #define ABSL_INTERNAL_DISABLE_DEPRECATED_DECLARATION_WARNING \ 707 _Pragma("GCC diagnostic push") \ 708 _Pragma("GCC diagnostic ignored \"-Wdeprecated-declarations\"") 709 #define ABSL_INTERNAL_RESTORE_DEPRECATED_DECLARATION_WARNING \ 710 _Pragma("GCC diagnostic pop") 711 #elif defined(_MSC_VER) 712 #define ABSL_INTERNAL_DISABLE_DEPRECATED_DECLARATION_WARNING \ 713 _Pragma("warning(push)") _Pragma("warning(disable: 4996)") 714 #define ABSL_INTERNAL_RESTORE_DEPRECATED_DECLARATION_WARNING \ 715 _Pragma("warning(pop)") 716 #else 717 #define ABSL_INTERNAL_DISABLE_DEPRECATED_DECLARATION_WARNING 718 #define ABSL_INTERNAL_RESTORE_DEPRECATED_DECLARATION_WARNING 719 #endif // defined(__GNUC__) || defined(__clang__) 720 721 // ABSL_CONST_INIT 722 // 723 // A variable declaration annotated with the `ABSL_CONST_INIT` attribute will 724 // not compile (on supported platforms) unless the variable has a constant 725 // initializer. This is useful for variables with static and thread storage 726 // duration, because it guarantees that they will not suffer from the so-called 727 // "static init order fiasco". 728 // 729 // This attribute must be placed on the initializing declaration of the 730 // variable. Some compilers will give a -Wmissing-constinit warning when this 731 // attribute is placed on some other declaration but missing from the 732 // initializing declaration. 733 // 734 // In some cases (notably with thread_local variables), `ABSL_CONST_INIT` can 735 // also be used in a non-initializing declaration to tell the compiler that a 736 // variable is already initialized, reducing overhead that would otherwise be 737 // incurred by a hidden guard variable. Thus annotating all declarations with 738 // this attribute is recommended to potentially enhance optimization. 739 // 740 // Example: 741 // 742 // class MyClass { 743 // public: 744 // ABSL_CONST_INIT static MyType my_var; 745 // }; 746 // 747 // ABSL_CONST_INIT MyType MyClass::my_var = MakeMyType(...); 748 // 749 // For code or headers that are assured to only build with C++20 and up, prefer 750 // just using the standard `constinit` keyword directly over this macro. 751 // 752 // Note that this attribute is redundant if the variable is declared constexpr. 753 #if defined(__cpp_constinit) && __cpp_constinit >= 201907L 754 #define ABSL_CONST_INIT constinit 755 #elif ABSL_HAVE_CPP_ATTRIBUTE(clang::require_constant_initialization) 756 #define ABSL_CONST_INIT [[clang::require_constant_initialization]] 757 #else 758 #define ABSL_CONST_INIT 759 #endif 760 761 // ABSL_REQUIRE_EXPLICIT_INIT 762 // 763 // ABSL_REQUIRE_EXPLICIT_INIT is placed *after* the data members of an aggregate 764 // type to indicate that the annotated member must be explicitly initialized by 765 // the user whenever the aggregate is constructed. For example: 766 // 767 // struct Coord { 768 // int x ABSL_REQUIRE_EXPLICIT_INIT; 769 // int y ABSL_REQUIRE_EXPLICIT_INIT; 770 // }; 771 // Coord coord = {1}; // warning: field 'y' is not explicitly initialized 772 // 773 // Note that usage on C arrays is not supported in C++. 774 // Use a struct (such as std::array) to wrap the array member instead. 775 // 776 // Avoid applying this attribute to the members of non-aggregate types. 777 // The behavior within non-aggregates is unspecified and subject to change. 778 // 779 // Do NOT attempt to suppress or demote the error generated by this attribute. 780 // Just like with a missing function argument, it is a hard error by design. 781 // 782 // See the upstream documentation for more details: 783 // https://clang.llvm.org/docs/AttributeReference.html#require-explicit-initialization 784 #ifdef __cplusplus 785 #if ABSL_HAVE_CPP_ATTRIBUTE(clang::require_explicit_initialization) 786 // clang-format off 787 #define ABSL_REQUIRE_EXPLICIT_INIT \ 788 [[clang::require_explicit_initialization]] = \ 789 AbslInternal_YouForgotToExplicitlyInitializeAField::v 790 #else 791 #define ABSL_REQUIRE_EXPLICIT_INIT \ 792 = AbslInternal_YouForgotToExplicitlyInitializeAField::v 793 #endif 794 // clang-format on 795 #else 796 // clang-format off 797 #if ABSL_HAVE_ATTRIBUTE(require_explicit_initialization) 798 #define ABSL_REQUIRE_EXPLICIT_INIT \ 799 __attribute__((require_explicit_initialization)) 800 #else 801 #define ABSL_REQUIRE_EXPLICIT_INIT \ 802 /* No portable fallback for C is available */ 803 #endif 804 // clang-format on 805 #endif 806 807 #ifdef __cplusplus 808 struct AbslInternal_YouForgotToExplicitlyInitializeAField { 809 // A portable version of [[clang::require_explicit_initialization]] that 810 // never builds, as a last resort for all toolchains. 811 // The error messages are poor, so we don't rely on this unless we have to. 812 template <class T> 813 #if !defined(SWIG) 814 constexpr 815 #endif 816 operator T() const /* NOLINT */ { 817 const void *volatile deliberately_volatile_ptr = nullptr; 818 // Infinite loop to prevent constexpr compilation 819 for (;;) { 820 // This assignment ensures the 'this' pointer is not optimized away, so 821 // that linking always fails. 822 deliberately_volatile_ptr = this; // Deliberately not constexpr 823 (void)deliberately_volatile_ptr; 824 } 825 } 826 // This is deliberately left undefined to prevent linking 827 static AbslInternal_YouForgotToExplicitlyInitializeAField v; 828 }; 829 #endif 830 831 // ABSL_ATTRIBUTE_PURE_FUNCTION 832 // 833 // ABSL_ATTRIBUTE_PURE_FUNCTION is used to annotate declarations of "pure" 834 // functions. A function is pure if its return value is only a function of its 835 // arguments. The pure attribute prohibits a function from modifying the state 836 // of the program that is observable by means other than inspecting the 837 // function's return value. Declaring such functions with the pure attribute 838 // allows the compiler to avoid emitting some calls in repeated invocations of 839 // the function with the same argument values. 840 // 841 // Example: 842 // 843 // ABSL_ATTRIBUTE_PURE_FUNCTION std::string FormatTime(Time t); 844 #if ABSL_HAVE_CPP_ATTRIBUTE(gnu::pure) 845 #define ABSL_ATTRIBUTE_PURE_FUNCTION [[gnu::pure]] 846 #elif ABSL_HAVE_ATTRIBUTE(pure) 847 #define ABSL_ATTRIBUTE_PURE_FUNCTION __attribute__((pure)) 848 #else 849 // If the attribute isn't defined, we'll fallback to ABSL_MUST_USE_RESULT since 850 // pure functions are useless if its return is ignored. 851 #define ABSL_ATTRIBUTE_PURE_FUNCTION ABSL_MUST_USE_RESULT 852 #endif 853 854 // ABSL_ATTRIBUTE_CONST_FUNCTION 855 // 856 // ABSL_ATTRIBUTE_CONST_FUNCTION is used to annotate declarations of "const" 857 // functions. A const function is similar to a pure function, with one 858 // exception: Pure functions may return value that depend on a non-volatile 859 // object that isn't provided as a function argument, while the const function 860 // is guaranteed to return the same result given the same arguments. 861 // 862 // Example: 863 // 864 // ABSL_ATTRIBUTE_CONST_FUNCTION int64_t ToInt64Milliseconds(Duration d); 865 #if defined(_MSC_VER) && !defined(__clang__) 866 // Put the MSVC case first since MSVC seems to parse const as a C++ keyword. 867 #define ABSL_ATTRIBUTE_CONST_FUNCTION ABSL_ATTRIBUTE_PURE_FUNCTION 868 #elif ABSL_HAVE_CPP_ATTRIBUTE(gnu::const) 869 #define ABSL_ATTRIBUTE_CONST_FUNCTION [[gnu::const]] 870 #elif ABSL_HAVE_ATTRIBUTE(const) 871 #define ABSL_ATTRIBUTE_CONST_FUNCTION __attribute__((const)) 872 #else 873 // Since const functions are more restrictive pure function, we'll fallback to a 874 // pure function if the const attribute is not handled. 875 #define ABSL_ATTRIBUTE_CONST_FUNCTION ABSL_ATTRIBUTE_PURE_FUNCTION 876 #endif 877 878 // ABSL_ATTRIBUTE_LIFETIME_BOUND indicates that a resource owned by a function 879 // parameter or implicit object parameter is retained by the return value of the 880 // annotated function (or, for a parameter of a constructor, in the value of the 881 // constructed object). This attribute causes warnings to be produced if a 882 // temporary object does not live long enough. 883 // 884 // When applied to a reference parameter, the referenced object is assumed to be 885 // retained by the return value of the function. When applied to a non-reference 886 // parameter (for example, a pointer or a class type), all temporaries 887 // referenced by the parameter are assumed to be retained by the return value of 888 // the function. 889 // 890 // See also the upstream documentation: 891 // https://clang.llvm.org/docs/AttributeReference.html#lifetimebound 892 // https://learn.microsoft.com/en-us/cpp/code-quality/c26816?view=msvc-170 893 #if ABSL_HAVE_CPP_ATTRIBUTE(clang::lifetimebound) 894 #define ABSL_ATTRIBUTE_LIFETIME_BOUND [[clang::lifetimebound]] 895 #elif ABSL_HAVE_CPP_ATTRIBUTE(msvc::lifetimebound) 896 #define ABSL_ATTRIBUTE_LIFETIME_BOUND [[msvc::lifetimebound]] 897 #elif ABSL_HAVE_ATTRIBUTE(lifetimebound) 898 #define ABSL_ATTRIBUTE_LIFETIME_BOUND __attribute__((lifetimebound)) 899 #else 900 #define ABSL_ATTRIBUTE_LIFETIME_BOUND 901 #endif 902 903 // Internal attribute; name and documentation TBD. 904 // 905 // See the upstream documentation: 906 // https://clang.llvm.org/docs/AttributeReference.html#lifetime_capture_by 907 #if ABSL_HAVE_CPP_ATTRIBUTE(clang::lifetime_capture_by) 908 #define ABSL_INTERNAL_ATTRIBUTE_CAPTURED_BY(Owner) \ 909 [[clang::lifetime_capture_by(Owner)]] 910 #else 911 #define ABSL_INTERNAL_ATTRIBUTE_CAPTURED_BY(Owner) 912 #endif 913 914 // ABSL_ATTRIBUTE_VIEW indicates that a type is solely a "view" of data that it 915 // points to, similarly to a span, string_view, or other non-owning reference 916 // type. 917 // This enables diagnosing certain lifetime issues similar to those enabled by 918 // ABSL_ATTRIBUTE_LIFETIME_BOUND, such as: 919 // 920 // struct ABSL_ATTRIBUTE_VIEW StringView { 921 // template<class R> 922 // StringView(const R&); 923 // }; 924 // 925 // StringView f(std::string s) { 926 // return s; // warning: address of stack memory returned 927 // } 928 // 929 // We disable this on Clang versions < 13 because of the following 930 // false-positive: 931 // 932 // absl::string_view f(absl::optional<absl::string_view> sv) { return *sv; } 933 // 934 // See the following links for details: 935 // https://reviews.llvm.org/D64448 936 // https://lists.llvm.org/pipermail/cfe-dev/2018-November/060355.html 937 #if ABSL_HAVE_CPP_ATTRIBUTE(gsl::Pointer) && \ 938 (!defined(__clang_major__) || __clang_major__ >= 13) 939 #define ABSL_ATTRIBUTE_VIEW [[gsl::Pointer]] 940 #else 941 #define ABSL_ATTRIBUTE_VIEW 942 #endif 943 944 // ABSL_ATTRIBUTE_OWNER indicates that a type is a container, smart pointer, or 945 // similar class that owns all the data that it points to. 946 // This enables diagnosing certain lifetime issues similar to those enabled by 947 // ABSL_ATTRIBUTE_LIFETIME_BOUND, such as: 948 // 949 // struct ABSL_ATTRIBUTE_VIEW StringView { 950 // template<class R> 951 // StringView(const R&); 952 // }; 953 // 954 // struct ABSL_ATTRIBUTE_OWNER String {}; 955 // 956 // StringView f(String s) { 957 // return s; // warning: address of stack memory returned 958 // } 959 // 960 // We disable this on Clang versions < 13 because of the following 961 // false-positive: 962 // 963 // absl::string_view f(absl::optional<absl::string_view> sv) { return *sv; } 964 // 965 // See the following links for details: 966 // https://reviews.llvm.org/D64448 967 // https://lists.llvm.org/pipermail/cfe-dev/2018-November/060355.html 968 #if ABSL_HAVE_CPP_ATTRIBUTE(gsl::Owner) && \ 969 (!defined(__clang_major__) || __clang_major__ >= 13) 970 #define ABSL_ATTRIBUTE_OWNER [[gsl::Owner]] 971 #else 972 #define ABSL_ATTRIBUTE_OWNER 973 #endif 974 975 // ABSL_ATTRIBUTE_TRIVIAL_ABI 976 // Indicates that a type is "trivially relocatable" -- meaning it can be 977 // relocated without invoking the constructor/destructor, using a form of move 978 // elision. 979 // 980 // From a memory safety point of view, putting aside destructor ordering, it's 981 // safe to apply ABSL_ATTRIBUTE_TRIVIAL_ABI if an object's location 982 // can change over the course of its lifetime: if a constructor can be run one 983 // place, and then the object magically teleports to another place where some 984 // methods are run, and then the object teleports to yet another place where it 985 // is destroyed. This is notably not true for self-referential types, where the 986 // move-constructor must keep the self-reference up to date. If the type changed 987 // location without invoking the move constructor, it would have a dangling 988 // self-reference. 989 // 990 // The use of this teleporting machinery means that the number of paired 991 // move/destroy operations can change, and so it is a bad idea to apply this to 992 // a type meant to count the number of moves. 993 // 994 // Warning: applying this can, rarely, break callers. Objects passed by value 995 // will be destroyed at the end of the call, instead of the end of the 996 // full-expression containing the call. In addition, it changes the ABI 997 // of functions accepting this type by value (e.g. to pass in registers). 998 // 999 // See also the upstream documentation: 1000 // https://clang.llvm.org/docs/AttributeReference.html#trivial-abi 1001 // 1002 // b/321691395 - This is currently disabled in open-source builds since 1003 // compiler support differs. If system libraries compiled with GCC are mixed 1004 // with libraries compiled with Clang, types will have different ideas about 1005 // their ABI, leading to hard to debug crashes. 1006 #define ABSL_ATTRIBUTE_TRIVIAL_ABI 1007 1008 // ABSL_ATTRIBUTE_NO_UNIQUE_ADDRESS 1009 // 1010 // Indicates a data member can be optimized to occupy no space (if it is empty) 1011 // and/or its tail padding can be used for other members. 1012 // 1013 // For code that is assured to only build with C++20 or later, prefer using 1014 // the standard attribute `[[no_unique_address]]` directly instead of this 1015 // macro. 1016 // 1017 // https://devblogs.microsoft.com/cppblog/msvc-cpp20-and-the-std-cpp20-switch/#c20-no_unique_address 1018 // Current versions of MSVC have disabled `[[no_unique_address]]` since it 1019 // breaks ABI compatibility, but offers `[[msvc::no_unique_address]]` for 1020 // situations when it can be assured that it is desired. Since Abseil does not 1021 // claim ABI compatibility in mixed builds, we can offer it unconditionally. 1022 #if defined(_MSC_VER) && _MSC_VER >= 1929 1023 #define ABSL_ATTRIBUTE_NO_UNIQUE_ADDRESS [[msvc::no_unique_address]] 1024 #elif ABSL_HAVE_CPP_ATTRIBUTE(no_unique_address) 1025 #define ABSL_ATTRIBUTE_NO_UNIQUE_ADDRESS [[no_unique_address]] 1026 #else 1027 #define ABSL_ATTRIBUTE_NO_UNIQUE_ADDRESS 1028 #endif 1029 1030 // ABSL_ATTRIBUTE_UNINITIALIZED 1031 // 1032 // GCC and Clang support a flag `-ftrivial-auto-var-init=<option>` (<option> 1033 // can be "zero" or "pattern") that can be used to initialize automatic stack 1034 // variables. Variables with this attribute will be left uninitialized, 1035 // overriding the compiler flag. 1036 // 1037 // See https://clang.llvm.org/docs/AttributeReference.html#uninitialized 1038 // and https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html#index-uninitialized-variable-attribute 1039 #if ABSL_HAVE_CPP_ATTRIBUTE(clang::uninitialized) 1040 #define ABSL_ATTRIBUTE_UNINITIALIZED [[clang::uninitialized]] 1041 #elif ABSL_HAVE_CPP_ATTRIBUTE(gnu::uninitialized) 1042 #define ABSL_ATTRIBUTE_UNINITIALIZED [[gnu::uninitialized]] 1043 #elif ABSL_HAVE_ATTRIBUTE(uninitialized) 1044 #define ABSL_ATTRIBUTE_UNINITIALIZED __attribute__((uninitialized)) 1045 #else 1046 #define ABSL_ATTRIBUTE_UNINITIALIZED 1047 #endif 1048 1049 // ABSL_ATTRIBUTE_WARN_UNUSED 1050 // 1051 // Compilers routinely warn about trivial variables that are unused. For 1052 // non-trivial types, this warning is suppressed since the 1053 // constructor/destructor may be intentional and load-bearing, for example, with 1054 // a RAII scoped lock. 1055 // 1056 // For example: 1057 // 1058 // class ABSL_ATTRIBUTE_WARN_UNUSED MyType { 1059 // public: 1060 // MyType(); 1061 // ~MyType(); 1062 // }; 1063 // 1064 // void foo() { 1065 // // Warns with ABSL_ATTRIBUTE_WARN_UNUSED attribute present. 1066 // MyType unused; 1067 // } 1068 // 1069 // See https://clang.llvm.org/docs/AttributeReference.html#warn-unused and 1070 // https://gcc.gnu.org/onlinedocs/gcc/C_002b_002b-Attributes.html#index-warn_005funused-type-attribute 1071 #if ABSL_HAVE_CPP_ATTRIBUTE(gnu::warn_unused) 1072 #define ABSL_ATTRIBUTE_WARN_UNUSED [[gnu::warn_unused]] 1073 #else 1074 #define ABSL_ATTRIBUTE_WARN_UNUSED 1075 #endif 1076 1077 #endif // ABSL_BASE_ATTRIBUTES_H_