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/memory/raw_ptr_exclusion.h"
  12 #include "base/trace_event/base_tracing_forward.h"
  13 #include "build/build_config.h"
  14
  15 namespace base {
  16
  17 // Location provides basic info where of an object was constructed, or was
  18 // significantly brought to life.
  19 class BASE_EXPORT Location {
  20  public:
  21   Location();
  22   Location(const Location& other);
  23   Location(Location&& other) noexcept;
  24   Location& operator=(const Location& other);
  25
  26   static Location CreateForTesting(const char* function_name,
  27                                    const char* file_name,
  28                                    int line_number,
  29                                    const void* program_counter) {
  30     return Location(function_name, file_name, line_number, program_counter);
  31   }
  32
  33   // Comparator for testing. The program counter should uniquely
  34   // identify a location.
  35   bool operator==(const Location& other) const {
  36     return program_counter_ == other.program_counter_;
  37   }
  38
  39   // Comparator is necessary to use location object within an ordered container
  40   // type (eg. std::map).
  41   bool operator<(const Location& other) const {
  42     return program_counter_ < other.program_counter_;
  43   }
  44
  45   // Returns true if there is source code location info. If this is false,
  46   // the Location object only contains a program counter or is
  47   // default-initialized (the program counter is also null).
  48   bool has_source_info() const { return function_name_ && file_name_; }
  49
  50   // Will be nullptr for default initialized Location objects and when source
  51   // names are disabled.
  52   const char* function_name() const { return function_name_; }
  53
  54   // Will be nullptr for default initialized Location objects and when source
  55   // names are disabled.
  56   const char* file_name() const { return file_name_; }
  57
  58   // Will be -1 for default initialized Location objects and when source names
  59   // are disabled.
  60   int line_number() const { return line_number_; }
  61
  62   // The address of the code generating this Location object. Should always be
  63   // valid except for default initialized Location objects, which will be
  64   // nullptr.
  65   const void* program_counter() const { return program_counter_; }
  66
  67   // Converts to the most user-readable form possible. If function and filename
  68   // are not available, this will return "pc:<hex address>".
  69   std::string ToString() const;
  70
  71   // Write a representation of this object into a trace.
  72   void WriteIntoTrace(perfetto::TracedValue context) const;
  73
  74   static Location Current(const char* function_name = __builtin_FUNCTION(),
  75                           const char* file_name = __builtin_FILE(),
  76                           int line_number = __builtin_LINE());
  77
  78  private:
  79   // Only initializes the file name and program counter, the source information
  80   // will be null for the strings, and -1 for the line number.
  81   // TODO(http://crbug.com/760702) remove file name from this constructor.
  82   Location(const char* file_name, const void* program_counter);
  83
  84   // Constructor should be called with a long-lived char*, such as __FILE__.
  85   // It assumes the provided value will persist as a global constant, and it
  86   // will not make a copy of it.
  87   Location(const char* function_name,
  88            const char* file_name,
  89            int line_number,
  90            const void* program_counter);
  91
  92   const char* function_name_ = nullptr;
  93   const char* file_name_ = nullptr;
  94   int line_number_ = -1;
  95
  96   // `program_counter_` is not a raw_ptr<...> for performance reasons (based on
  97   // analysis of sampling profiler data and tab_search:top100:2020).
  98   RAW_PTR_EXCLUSION const void* program_counter_ = nullptr;
  99 };
 100
 101 BASE_EXPORT const void* GetProgramCounter();
 102
 103 #define FROM_HERE ::base::Location::Current()
 104
 105 }  // namespace base
 106
 107 #endif  // BASE_LOCATION_H_