diff options
Diffstat (limited to 'absl/base/attributes.h')
| -rw-r--r-- | absl/base/attributes.h | 226 |
1 files changed, 146 insertions, 80 deletions
diff --git a/absl/base/attributes.h b/absl/base/attributes.h index 5eecdabedb16..c2155a4e213d 100644 --- a/absl/base/attributes.h +++ b/absl/base/attributes.h @@ -12,39 +12,61 @@ // See the License for the specific language governing permissions and // limitations under the License. // -// Various macros for C++ attributes +// This header file defines macros for declaring attributes for functions, +// types, and variables. +// +// These macros are used within Abseil and allow the compiler to optimize, where +// applicable, certain function calls. +// // This file is used for both C and C++! // // Most macros here are exposing GCC or Clang features, and are stubbed out for // other compilers. +// // GCC attributes documentation: -// https://gcc.gnu.org/onlinedocs/gcc-4.7.0/gcc/Function-Attributes.html -// https://gcc.gnu.org/onlinedocs/gcc-4.7.0/gcc/Variable-Attributes.html -// https://gcc.gnu.org/onlinedocs/gcc-4.7.0/gcc/Type-Attributes.html -// -// Most attributes in this file are already supported by GCC 4.7. -// However, some of them are not supported in older version of Clang. -// Thus, we check __has_attribute() first. If the check fails, we check if we -// are on GCC and assume the attribute exists on GCC (which is verified on GCC -// 4.7). -// -// For sanitizer-related attributes, define the following macros -// using -D along with the given value for -fsanitize: -// - ADDRESS_SANITIZER with -fsanitize=address (GCC 4.8+, Clang) -// - MEMORY_SANITIZER with -fsanitize=memory (Clang) -// - THREAD_SANITIZER with -fsanitize=thread (GCC 4.8+, Clang) -// - UNDEFINED_BEHAVIOR_SANITIZER with -fsanitize=undefined (GCC 4.9+, Clang) -// - CONTROL_FLOW_INTEGRITY with -fsanitize=cfi (Clang) -// Since these are only supported by GCC and Clang now, we only check for -// __GNUC__ (GCC or Clang) and the above macros. +// https://gcc.gnu.org/onlinedocs/gcc-4.7.0/gcc/Function-Attributes.html +// https://gcc.gnu.org/onlinedocs/gcc-4.7.0/gcc/Variable-Attributes.html +// https://gcc.gnu.org/onlinedocs/gcc-4.7.0/gcc/Type-Attributes.html +// +// Most attributes in this file are already supported by GCC 4.7. However, some +// of them are not supported in older version of Clang. Thus, we check +// `__has_attribute()` first. If the check fails, we check if we are on GCC and +// assume the attribute exists on GCC (which is verified on GCC 4.7). +// +// ----------------------------------------------------------------------------- +// Sanitizer Attributes +// ----------------------------------------------------------------------------- +// +// Sanitizer-related attributes are not "defined" in this file (and indeed +// are not defined as such in any file). To utilize the following +// sanitizer-related attributes within your builds, define the following macros +// within your build using a `-D` flag, along with the given value for +// `-fsanitize`: +// +// * `ADDRESS_SANITIZER` + `-fsanitize=address` (Clang, GCC 4.8) +// * `MEMORY_SANITIZER` + `-fsanitize=memory` (Clang-only) +// * `THREAD_SANITIZER + `-fsanitize=thread` (Clang, GCC 4.8+) +// * `UNDEFINED_BEHAVIOR_SANITIZER` + `-fsanitize=undefined` (Clang, GCC 4.9+) +// * `CONTROL_FLOW_INTEGRITY` + -fsanitize=cfi (Clang-only) +// +// Example: +// +// // Enable branches in the Abseil code that are tagged for ASan: +// $ bazel -D ADDRESS_SANITIZER -fsanitize=address *target* +// +// Since these macro names are only supported by GCC and Clang, we only check +// for `__GNUC__` (GCC or Clang) and the above macros. #ifndef ABSL_BASE_ATTRIBUTES_H_ #define ABSL_BASE_ATTRIBUTES_H_ -// ABSL_HAVE_ATTRIBUTE is a function-like feature checking macro. -// It's a wrapper around __has_attribute, which is defined by GCC 5+ and Clang. -// It evaluates to a nonzero constant integer if the attribute is supported -// or 0 if not. -// It evaluates to zero if __has_attribute is not defined by the compiler. +// ABSL_HAVE_ATTRIBUTE +// +// A function-like feature checking macro that is a wrapper around +// `__has_attribute`, which is defined by GCC 5+ and Clang and evaluates to a +// nonzero constant integer if the attribute is supported or 0 if not. +// +// It evaluates to zero if `__has_attribute` is not defined by the compiler. +// // GCC: https://gcc.gnu.org/gcc-5/changes.html // Clang: https://clang.llvm.org/docs/LanguageExtensions.html #ifdef __has_attribute @@ -53,11 +75,12 @@ #define ABSL_HAVE_ATTRIBUTE(x) 0 #endif -// ABSL_HAVE_CPP_ATTRIBUTE is a function-like feature checking macro that -// accepts C++11 style attributes. It's a wrapper around __has_cpp_attribute, -// defined by ISO C++ SD-6 +// ABSL_HAVE_CPP_ATTRIBUTE +// +// A function-like feature checking macro that accepts C++11 style attributes. +// It's a wrapper around `__has_cpp_attribute`, defined by ISO C++ SD-6 // (http://en.cppreference.com/w/cpp/experimental/feature_test). If we don't -// find __has_cpp_attribute, will evaluate to 0. +// find `__has_cpp_attribute`, will evaluate to 0. #if defined(__cplusplus) && defined(__has_cpp_attribute) // NOTE: requiring __cplusplus above should not be necessary, but // works around https://bugs.llvm.org/show_bug.cgi?id=23435. @@ -69,15 +92,18 @@ // ----------------------------------------------------------------------------- // Function Attributes // ----------------------------------------------------------------------------- +// // GCC: https://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html // Clang: https://clang.llvm.org/docs/AttributeReference.html -// ABSL_PRINTF_ATTRIBUTE, ABSL_SCANF_ATTRIBUTE -// Tell the compiler to do printf format std::string checking if the +// ABSL_PRINTF_ATTRIBUTE +// ABSL_SCANF_ATTRIBUTE +// +// Tells the compiler to perform `printf` format std::string checking if the // compiler supports it; see the 'format' attribute in // <http://gcc.gnu.org/onlinedocs/gcc-4.7.0/gcc/Function-Attributes.html>. // -// N.B.: As the GCC manual states, "[s]ince non-static C++ methods +// Note: As the GCC manual states, "[s]ince non-static C++ methods // have an implicit 'this' argument, the arguments of such methods // should be counted from two, not one." #if ABSL_HAVE_ATTRIBUTE(format) || (defined(__GNUC__) && !defined(__clang__)) @@ -90,9 +116,10 @@ #define ABSL_SCANF_ATTRIBUTE(string_index, first_to_check) #endif -// ABSL_ATTRIBUTE_ALWAYS_INLINE, ABSL_ATTRIBUTE_NOINLINE -// For functions we want to force inline or not inline. -// Introduced in gcc 3.1. +// ABSL_ATTRIBUTE_ALWAYS_INLINE +// ABSL_ATTRIBUTE_NOINLINE +// +// Forces functions to either inline or not inline. Introduced in gcc 3.1. #if ABSL_HAVE_ATTRIBUTE(always_inline) || \ (defined(__GNUC__) && !defined(__clang__)) #define ABSL_ATTRIBUTE_ALWAYS_INLINE __attribute__((always_inline)) @@ -109,7 +136,8 @@ #endif // ABSL_ATTRIBUTE_NO_TAIL_CALL -// Prevent the compiler from optimizing away stack frames for functions which +// +// Prevents the compiler from optimizing away stack frames for functions which // end in a call to another function. #if ABSL_HAVE_ATTRIBUTE(disable_tail_calls) #define ABSL_HAVE_ATTRIBUTE_NO_TAIL_CALL 1 @@ -122,8 +150,10 @@ #define ABSL_ATTRIBUTE_NO_TAIL_CALL #define ABSL_HAVE_ATTRIBUTE_NO_TAIL_CALL 0 #endif + // ABSL_ATTRIBUTE_WEAK -// For weak functions +// +// Tags a function as weak for the purposes of compilation and linking. #if ABSL_HAVE_ATTRIBUTE(weak) || (defined(__GNUC__) && !defined(__clang__)) #undef ABSL_ATTRIBUTE_WEAK #define ABSL_ATTRIBUTE_WEAK __attribute__((weak)) @@ -132,9 +162,11 @@ #define ABSL_ATTRIBUTE_WEAK #define ABSL_HAVE_ATTRIBUTE_WEAK 0 #endif + // ABSL_ATTRIBUTE_NONNULL -// Tell the compiler either that a particular function parameter -// should be a non-null pointer, or that all pointer arguments should +// +// Tells the compiler either (a) that a particular function parameter +// should be a non-null pointer, or (b) that all pointer arguments should // be non-null. // // Note: As the GCC manual states, "[s]ince non-static C++ methods @@ -142,10 +174,13 @@ // should be counted from two, not one." // // Args are indexed starting at 1. -// For non-static class member functions, the implicit "this" argument -// is arg 1, and the first explicit argument is arg 2. -// For static class member functions, there is no implicit "this", and -// the first explicit argument is arg 1. +// +// For non-static class member functions, the implicit `this` argument +// is arg 1, and the first explicit argument is arg 2. For static class member +// functions, there is no implicit `this`, and the first explicit argument is +// arg 1. +// +// Example: // // /* arg_a cannot be null, but arg_b can */ // void Function(void* arg_a, void* arg_b) ABSL_ATTRIBUTE_NONNULL(1); @@ -171,8 +206,10 @@ #else #define ABSL_ATTRIBUTE_NONNULL(...) #endif + // ABSL_ATTRIBUTE_NORETURN -// Tell the compiler that a given function never returns +// +// Tells the compiler that a given function never returns. #if ABSL_HAVE_ATTRIBUTE(noreturn) || (defined(__GNUC__) && !defined(__clang__)) #define ABSL_ATTRIBUTE_NORETURN __attribute__((noreturn)) #elif defined(_MSC_VER) @@ -180,8 +217,10 @@ #else #define ABSL_ATTRIBUTE_NORETURN #endif + // ABSL_ATTRIBUTE_NO_SANITIZE_ADDRESS -// Tell AddressSanitizer (or other memory testing tools) to ignore a given +// +// Tells the AddressSanitizer (or other memory testing tools) to ignore a given // function. Useful for cases when a function reads random locations on stack, // calls _exit from a cloned subprocess, deliberately accesses buffer // out of bounds or does other scary things with memory. @@ -194,11 +233,12 @@ #endif // ABSL_ATTRIBUTE_NO_SANITIZE_MEMORY -// Tell MemorySanitizer to relax the handling of a given function. All "Use of -// uninitialized value" warnings from such functions will be suppressed, and all -// values loaded from memory will be considered fully initialized. -// This is similar to the ADDRESS_SANITIZER attribute above, but deals with -// initializedness rather than addressability issues. +// +// Tells the MemorySanitizer to relax the handling of a given function. All +// "Use of uninitialized value" warnings from such functions will be suppressed, +// and all values loaded from memory will be considered fully initialized. +// This attribute is similar to the ADDRESS_SANITIZER attribute above, but deals +// with initialized-ness rather than addressability issues. // NOTE: MemorySanitizer(msan) is supported by Clang but not GCC. #if defined(__GNUC__) && defined(MEMORY_SANITIZER) #define ABSL_ATTRIBUTE_NO_SANITIZE_MEMORY __attribute__((no_sanitize_memory)) @@ -207,8 +247,8 @@ #endif // ABSL_ATTRIBUTE_NO_SANITIZE_THREAD -// Tell ThreadSanitizer to not instrument a given function. -// If you are adding this attribute, please cc dynamic-tools@ on the cl. +// +// Tells the ThreadSanitizer to not instrument a given function. // NOTE: GCC supports ThreadSanitizer(tsan) since 4.8. // https://gcc.gnu.org/gcc-4.8/changes.html #if defined(__GNUC__) && defined(THREAD_SANITIZER) @@ -218,7 +258,8 @@ #endif // ABSL_ATTRIBUTE_NO_SANITIZE_UNDEFINED -// Tell UndefinedSanitizer to ignore a given function. Useful for cases +// +// Tells the UndefinedSanitizer to ignore a given function. Useful for cases // where certain behavior (eg. devision by zero) is being used intentionally. // NOTE: GCC supports UndefinedBehaviorSanitizer(ubsan) since 4.9. // https://gcc.gnu.org/gcc-4.9/changes.html @@ -231,7 +272,8 @@ #endif // ABSL_ATTRIBUTE_NO_SANITIZE_CFI -// Tell ControlFlowIntegrity sanitizer to not instrument a given function. +// +// Tells the ControlFlowIntegrity sanitizer to not instrument a given function. // See https://clang.llvm.org/docs/ControlFlowIntegrity.html for details. #if defined(__GNUC__) && defined(CONTROL_FLOW_INTEGRITY) #define ABSL_ATTRIBUTE_NO_SANITIZE_CFI __attribute__((no_sanitize("cfi"))) @@ -239,33 +281,42 @@ #define ABSL_ATTRIBUTE_NO_SANITIZE_CFI #endif -// ABSL_ATTRIBUTE_SECTION -// Labeled sections are not supported on Darwin/iOS. +// ABSL_HAVE_ATTRIBUTE_SECTION +// +// Indicates whether labeled sections are supported. Labeled sections are not +// supported on Darwin/iOS. #ifdef ABSL_HAVE_ATTRIBUTE_SECTION #error ABSL_HAVE_ATTRIBUTE_SECTION cannot be directly set #elif (ABSL_HAVE_ATTRIBUTE(section) || \ (defined(__GNUC__) && !defined(__clang__))) && \ !defined(__APPLE__) #define ABSL_HAVE_ATTRIBUTE_SECTION 1 + +// ABSL_ATTRIBUTE_SECTION // -// Tell the compiler/linker to put a given function into a section and define -// "__start_ ## name" and "__stop_ ## name" symbols to bracket the section. -// This functionality is supported by GNU linker. -// Any function with ABSL_ATTRIBUTE_SECTION must not be inlined, or it will -// be placed into whatever section its caller is placed into. +// Tells the compiler/linker to put a given function into a section and define +// `__start_ ## name` and `__stop_ ## name` symbols to bracket the section. +// This functionality is supported by GNU linker. Any function annotated with +// `ABSL_ATTRIBUTE_SECTION` must not be inlined, or it will be placed into +// whatever section its caller is placed into. // #ifndef ABSL_ATTRIBUTE_SECTION #define ABSL_ATTRIBUTE_SECTION(name) \ __attribute__((section(#name))) __attribute__((noinline)) #endif -// Tell the compiler/linker to put a given variable into a section and define -// "__start_ ## name" and "__stop_ ## name" symbols to bracket the section. + +// ABSL_ATTRIBUTE_SECTION_VARIABLE +// +// Tells the compiler/linker to put a given variable into a section and define +// `__start_ ## name` and `__stop_ ## name` symbols to bracket the section. // This functionality is supported by GNU linker. #ifndef ABSL_ATTRIBUTE_SECTION_VARIABLE #define ABSL_ATTRIBUTE_SECTION_VARIABLE(name) __attribute__((section(#name))) #endif + +// ABSL_DECLARE_ATTRIBUTE_SECTION_VARS // -// Weak section declaration to be used as a global declaration +// A weak section declaration to be used as a global declaration // for ABSL_ATTRIBUTE_SECTION_START|STOP(name) to compile and link // even without functions with ABSL_ATTRIBUTE_SECTION(name). // ABSL_DEFINE_ATTRIBUTE_SECTION should be in the exactly one file; it's @@ -281,7 +332,9 @@ #define ABSL_DEFINE_ATTRIBUTE_SECTION_VARS(name) #endif -// Return void* pointers to start/end of a section of code with +// ABSL_ATTRIBUTE_SECTION_START +// +// Returns `void*` pointers to start/end of a section of code with // functions having ABSL_ATTRIBUTE_SECTION(name). // Returns 0 if no such functions exist. // One must ABSL_DECLARE_ATTRIBUTE_SECTION_VARS(name) for this to compile and @@ -306,6 +359,7 @@ #endif // ABSL_ATTRIBUTE_SECTION // ABSL_ATTRIBUTE_STACK_ALIGN_FOR_OLD_LIBC +// // Support for aligning the stack on 32-bit x86. #if ABSL_HAVE_ATTRIBUTE(force_align_arg_pointer) || \ (defined(__GNUC__) && !defined(__clang__)) @@ -326,10 +380,13 @@ #endif // ABSL_MUST_USE_RESULT -// Tell the compiler to warn about unused return values for functions declared +// +// Tells the compiler to warn about unused return values for functions declared // with this macro. The macro must appear as the very first part of a function // declaration or definition: // +// Example: +// // ABSL_MUST_USE_RESULT Sprocket* AllocateSprocket(); // // This placement has the broadest compatibility with GCC, Clang, and MSVC, with @@ -350,10 +407,14 @@ #endif // ABSL_ATTRIBUTE_HOT, ABSL_ATTRIBUTE_COLD -// Tell GCC that a function is hot or cold. GCC can use this information to +// +// Tells GCC that a function is hot or cold. GCC can use this information to // improve static analysis, i.e. a conditional branch to a cold function // is likely to be not-taken. -// This annotation is used for function declarations, e.g.: +// This annotation is used for function declarations. +// +// Example: +// // int foo() ABSL_ATTRIBUTE_HOT; #if ABSL_HAVE_ATTRIBUTE(hot) || (defined(__GNUC__) && !defined(__clang__)) #define ABSL_ATTRIBUTE_HOT __attribute__((hot)) @@ -382,12 +443,12 @@ // // These attributes only take effect when the following conditions are met: // -// - The file/target is built in at least C++11 mode, with a Clang compiler -// that supports XRay attributes. -// - The file/target is built with the -fxray-instrument flag set for the -// Clang/LLVM compiler. -// - The function is defined in the translation unit (the compiler honors the -// attribute in either the definition or the declaration, and must match). +// * The file/target is built in at least C++11 mode, with a Clang compiler +// that supports XRay attributes. +// * The file/target is built with the -fxray-instrument flag set for the +// Clang/LLVM compiler. +// * The function is defined in the translation unit (the compiler honors the +// attribute in either the definition or the declaration, and must match). // // There are cases when, even when building with XRay instrumentation, users // might want to control specifically which functions are instrumented for a @@ -422,7 +483,8 @@ // ----------------------------------------------------------------------------- // ABSL_ATTRIBUTE_UNUSED -// Prevent the compiler from complaining about or optimizing away variables +// +// Prevents the compiler from complaining about or optimizing away variables // that appear unused. #if ABSL_HAVE_ATTRIBUTE(unused) || (defined(__GNUC__) && !defined(__clang__)) #undef ABSL_ATTRIBUTE_UNUSED @@ -430,8 +492,10 @@ #else #define ABSL_ATTRIBUTE_UNUSED #endif + // ABSL_ATTRIBUTE_INITIAL_EXEC -// Tell the compiler to use "initial-exec" mode for a thread-local variable. +// +// Tells the compiler to use "initial-exec" mode for a thread-local variable. // See http://people.redhat.com/drepper/tls.pdf for the gory details. #if ABSL_HAVE_ATTRIBUTE(tls_model) || (defined(__GNUC__) && !defined(__clang__)) #define ABSL_ATTRIBUTE_INITIAL_EXEC __attribute__((tls_model("initial-exec"))) @@ -440,7 +504,8 @@ #endif // ABSL_ATTRIBUTE_PACKED -// Prevent the compiler from padding a structure to natural alignment +// +// Prevents the compiler from padding a structure to natural alignment #if ABSL_HAVE_ATTRIBUTE(packed) || (defined(__GNUC__) && !defined(__clang__)) #define ABSL_ATTRIBUTE_PACKED __attribute__((__packed__)) #else @@ -448,15 +513,16 @@ #endif // ABSL_CONST_INIT -// A variable declaration annotated with the ABSL_CONST_INIT attribute will +// +// A variable declaration annotated with the `ABSL_CONST_INIT` attribute will // not compile (on supported platforms) unless the variable has a constant // initializer. This is useful for variables with static and thread storage // duration, because it guarantees that they will not suffer from the so-called // "static init order fiasco". // -// Sample usage: +// Example: // -// ABSL_CONST_INIT static MyType my_var = MakeMyType(...); +// ABSL_CONST_INIT static MyType my_var = MakeMyType(...); // // Note that this attribute is redundant if the variable is declared constexpr. #if ABSL_HAVE_CPP_ATTRIBUTE(clang::require_constant_initialization) |