base/location.h

   1 // Copyright 2012 The Chromium Authors
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef BASE_LOCATION_H_
   6 #define BASE_LOCATION_H_
   7
   8 #include <string>
   9
  10 #include "base/base_export.h"
  11 #include "base/debug/debugging_buildflags.h"
  12 #include "base/memory/raw_ptr_exclusion.h"
  13 #include "base/trace_event/base_tracing_forward.h"
  14 #include "build/build_config.h"
  15
  16 namespace base {
  17
  18 #if defined(__clang__)
  19 // Clang allows detection of these builtins.
  20 #define SUPPORTS_LOCATION_BUILTINS                                       \
  21   (__has_builtin(__builtin_FUNCTION) && __has_builtin(__builtin_FILE) && \
  22    __has_builtin(__builtin_LINE))
  23 #elif defined(COMPILER_GCC) && __GNUC__ >= 7
  24 // GCC has supported these for a long time, but they point at the function
  25 // declaration in the case of default arguments, rather than at the call site.
  26 #define SUPPORTS_LOCATION_BUILTINS 1
  27 #else
  28 #define SUPPORTS_LOCATION_BUILTINS 0
  29 #endif
  30
  31 // Location provides basic info where of an object was constructed, or was
  32 // significantly brought to life.
  33 class BASE_EXPORT Location {
  34  public:
  35   Location();
  36   Location(const Location& other);
  37   Location(Location&& other) noexcept;
  38   Location& operator=(const Location& other);
  39
  40   // Only initializes the file name and program counter, the source information
  41   // will be null for the strings, and -1 for the line number.
  42   // TODO(http://crbug.com/760702) remove file name from this constructor.
  43   Location(const char* file_name, const void* program_counter);
  44
  45   // Constructor should be called with a long-lived char*, such as __FILE__.
  46   // It assumes the provided value will persist as a global constant, and it
  47   // will not make a copy of it.
  48   Location(const char* function_name,
  49            const char* file_name,
  50            int line_number,
  51            const void* program_counter);
  52
  53   // Comparator for testing. The program counter should uniquely
  54   // identify a location.
  55   bool operator==(const Location& other) const {
  56     return program_counter_ == other.program_counter_;
  57   }
  58
  59   // Comparator is necessary to use location object within an ordered container
  60   // type (eg. std::map).
  61   bool operator<(const Location& other) const {
  62     return program_counter_ < other.program_counter_;
  63   }
  64
  65   // Returns true if there is source code location info. If this is false,
  66   // the Location object only contains a program counter or is
  67   // default-initialized (the program counter is also null).
  68   bool has_source_info() const { return function_name_ && file_name_; }
  69
  70   // Will be nullptr for default initialized Location objects and when source
  71   // names are disabled.
  72   const char* function_name() const { return function_name_; }
  73
  74   // Will be nullptr for default initialized Location objects and when source
  75   // names are disabled.
  76   const char* file_name() const { return file_name_; }
  77
  78   // Will be -1 for default initialized Location objects and when source names
  79   // are disabled.
  80   int line_number() const { return line_number_; }
  81
  82   // The address of the code generating this Location object. Should always be
  83   // valid except for default initialized Location objects, which will be
  84   // nullptr.
  85   const void* program_counter() const { return program_counter_; }
  86
  87   // Converts to the most user-readable form possible. If function and filename
  88   // are not available, this will return "pc:<hex address>".
  89   std::string ToString() const;
  90
  91   // Write a representation of this object into a trace.
  92   void WriteIntoTrace(perfetto::TracedValue context) const;
  93
  94 #if !BUILDFLAG(FROM_HERE_USES_LOCATION_BUILTINS)
  95 #if !BUILDFLAG(ENABLE_LOCATION_SOURCE)
  96   static Location CreateFromHere(const char* file_name);
  97 #else
  98   static Location CreateFromHere(const char* function_name,
  99                                  const char* file_name,
 100                                  int line_number);
 101 #endif
 102 #endif
 103
 104 #if SUPPORTS_LOCATION_BUILTINS && BUILDFLAG(ENABLE_LOCATION_SOURCE)
 105   static Location Current(const char* function_name = __builtin_FUNCTION(),
 106                           const char* file_name = __builtin_FILE(),
 107                           int line_number = __builtin_LINE());
 108 #elif SUPPORTS_LOCATION_BUILTINS
 109   static Location Current(const char* file_name = __builtin_FILE());
 110 #else
 111   static Location Current();
 112 #endif
 113
 114  private:
 115   const char* function_name_ = nullptr;
 116   const char* file_name_ = nullptr;
 117   int line_number_ = -1;
 118
 119   // `program_counter_` is not a raw_ptr<...> for performance reasons (based on
 120   // analysis of sampling profiler data and tab_search:top100:2020).
 121   RAW_PTR_EXCLUSION const void* program_counter_ = nullptr;
 122 };
 123
 124 BASE_EXPORT const void* GetProgramCounter();
 125
 126 #if BUILDFLAG(FROM_HERE_USES_LOCATION_BUILTINS)
 127
 128 #define FROM_HERE ::base::Location::Current()
 129
 130 // The macros defined here will expand to the current function.
 131 #elif BUILDFLAG(ENABLE_LOCATION_SOURCE)
 132
 133 // Full source information should be included.
 134 #define FROM_HERE ::base::Location::CreateFromHere(__func__, __FILE__, __LINE__)
 135
 136 #else
 137
 138 // TODO(http://crbug.com/760702) remove the __FILE__ argument from these calls.
 139 #define FROM_HERE ::base::Location::CreateFromHere(__FILE__)
 140
 141 #endif
 142
 143 }  // namespace base
 144
 145 #endif  // BASE_LOCATION_H_