base/location.h

   1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
   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 <cassert>
   9 #include <string>
  10
  11 #include "base/base_export.h"
  12 #include "base/basictypes.h"
  13 #include "base/containers/hash_tables.h"
  14
  15 namespace tracked_objects {
  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   // Constructor should be called with a long-lived char*, such as __FILE__.
  22   // It assumes the provided value will persist as a global constant, and it
  23   // will not make a copy of it.
  24   Location(const char* function_name,
  25            const char* file_name,
  26            int line_number,
  27            const void* program_counter);
  28
  29   // Provide a default constructor for easy of debugging.
  30   Location();
  31
  32   // Copy constructor.
  33   Location(const Location& other);
  34
  35   // Comparator for hash map insertion.
  36   // No need to use |function_name_| since the other two fields uniquely
  37   // identify this location.
  38   bool operator==(const Location& other) const {
  39     return line_number_ == other.line_number_ &&
  40            file_name_ == other.file_name_;
  41   }
  42
  43   const char* function_name()   const { return function_name_; }
  44   const char* file_name()       const { return file_name_; }
  45   int line_number()             const { return line_number_; }
  46   const void* program_counter() const { return program_counter_; }
  47
  48   std::string ToString() const;
  49
  50   // Hash operator for hash maps.
  51   struct Hash {
  52     size_t operator()(const Location& location) const {
  53       // Compute the hash value using file name pointer and line number.
  54       // No need to use |function_name_| since the other two fields uniquely
  55       // identify this location.
  56
  57       // The file name will always be uniquely identified by its pointer since
  58       // it comes from __FILE__, so no need to check the contents of the string.
  59       // See the definition of FROM_HERE in location.h, and how it is used
  60       // elsewhere.
  61
  62       // Due to inconsistent definitions of uint64_t and uintptr_t, casting the
  63       // file name pointer to a uintptr_t causes a compiler error for some
  64       // platforms. The solution is to explicitly cast it to a uint64_t.
  65       return base::HashPair(reinterpret_cast<uint64_t>(location.file_name()),
  66                             location.line_number());
  67     }
  68   };
  69
  70   // Translate the some of the state in this instance into a human readable
  71   // string with HTML characters in the function names escaped, and append that
  72   // string to |output|.  Inclusion of the file_name_ and function_name_ are
  73   // optional, and controlled by the boolean arguments.
  74   void Write(bool display_filename, bool display_function_name,
  75              std::string* output) const;
  76
  77   // Write function_name_ in HTML with '<' and '>' properly encoded.
  78   void WriteFunctionName(std::string* output) const;
  79
  80  private:
  81   const char* function_name_;
  82   const char* file_name_;
  83   int line_number_;
  84   const void* program_counter_;
  85 };
  86
  87 // A "snapshotted" representation of the Location class that can safely be
  88 // passed across process boundaries.
  89 struct BASE_EXPORT LocationSnapshot {
  90   // The default constructor is exposed to support the IPC serialization macros.
  91   LocationSnapshot();
  92   explicit LocationSnapshot(const tracked_objects::Location& location);
  93   ~LocationSnapshot();
  94
  95   std::string file_name;
  96   std::string function_name;
  97   int line_number;
  98 };
  99
 100 BASE_EXPORT const void* GetProgramCounter();
 101
 102 // Define a macro to record the current source location.
 103 #define FROM_HERE FROM_HERE_WITH_EXPLICIT_FUNCTION(__FUNCTION__)
 104
 105 #define FROM_HERE_WITH_EXPLICIT_FUNCTION(function_name)                        \
 106     ::tracked_objects::Location(function_name,                                 \
 107                                 __FILE__,                                      \
 108                                 __LINE__,                                      \
 109                                 ::tracked_objects::GetProgramCounter())
 110
 111 }  // namespace tracked_objects
 112
 113 #endif  // BASE_LOCATION_H_