base/tracked.h

   1 // Copyright (c) 2011 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 //------------------------------------------------------------------------------
   6 // Tracked is the base class for all tracked objects.  During construction, it
   7 // registers the fact that an instance was created, and at destruction time, it
   8 // records that event.  The instance may be tagged with a name, which is refered
   9 // to as its Location.  The Location is a file and line number, most
  10 // typically indicated where the object was constructed.  In some cases, as the
  11 // object's significance is refined (for example, a Task object is augmented to
  12 // do additonal things), its Location may be redefined to that later location.
  13
  14 // Tracking includes (for each instance) recording the birth thread, death
  15 // thread, and duration of life (from construction to destruction).  All this
  16 // data is accumulated and filtered for review at about:objects.
  17
  18 #ifndef BASE_TRACKED_H_
  19 #define BASE_TRACKED_H_
  20 #pragma once
  21
  22 #include <string>
  23
  24 #include "base/base_api.h"
  25 #include "base/time.h"
  26
  27 #ifndef NDEBUG
  28 #ifndef TRACK_ALL_TASK_OBJECTS
  29 #define TRACK_ALL_TASK_OBJECTS
  30 #endif   // TRACK_ALL_TASK_OBJECTS
  31 #endif  // NDEBUG
  32
  33 namespace tracked_objects {
  34
  35 //------------------------------------------------------------------------------
  36 // Location provides basic info where of an object was constructed, or was
  37 // significantly brought to life.
  38
  39 class BASE_API Location {
  40  public:
  41   // Constructor should be called with a long-lived char*, such as __FILE__.
  42   // It assumes the provided value will persist as a global constant, and it
  43   // will not make a copy of it.
  44   Location(const char* function_name,
  45            const char* file_name,
  46            int line_number,
  47            const void* program_counter);
  48
  49   // Provide a default constructor for easy of debugging.
  50   Location();
  51
  52   // Comparison operator for insertion into a std::map<> hash tables.
  53   // All we need is *some* (any) hashing distinction.  Strings should already
  54   // be unique, so we don't bother with strcmp or such.
  55   // Use line number as the primary key (because it is fast, and usually gets us
  56   // a difference), and then pointers as secondary keys (just to get some
  57   // distinctions).
  58   bool operator < (const Location& other) const {
  59     if (line_number_ != other.line_number_)
  60       return line_number_ < other.line_number_;
  61     if (file_name_ != other.file_name_)
  62       return file_name_ < other.file_name_;
  63     return function_name_ < other.function_name_;
  64   }
  65
  66   const char* function_name()   const { return function_name_; }
  67   const char* file_name()       const { return file_name_; }
  68   int line_number()             const { return line_number_; }
  69   const void* program_counter() const { return program_counter_; }
  70
  71   void Write(bool display_filename, bool display_function_name,
  72              std::string* output) const;
  73
  74   // Write function_name_ in HTML with '<' and '>' properly encoded.
  75   void WriteFunctionName(std::string* output) const;
  76
  77  private:
  78   const char* const function_name_;
  79   const char* const file_name_;
  80   const int line_number_;
  81   const void* const program_counter_;
  82 };
  83
  84 BASE_API const void* GetProgramCounter();
  85
  86 //------------------------------------------------------------------------------
  87 // Define a macro to record the current source location.
  88
  89 #define FROM_HERE tracked_objects::Location(                                   \
  90     __FUNCTION__,                                                              \
  91     __FILE__,                                                                  \
  92     __LINE__,                                                                  \
  93     tracked_objects::GetProgramCounter())                                      \
  94
  95
  96 //------------------------------------------------------------------------------
  97
  98
  99 class Births;
 100
 101 class BASE_API Tracked {
 102  public:
 103   Tracked();
 104   virtual ~Tracked();
 105
 106   // Used to record the FROM_HERE location of a caller.
 107   void SetBirthPlace(const Location& from_here);
 108   const Location GetBirthPlace() const;
 109
 110   // When a task sits around a long time, such as in a timer, or object watcher,
 111   // this method should be called when the task becomes active, and its
 112   // significant lifetime begins (and its waiting to be woken up has passed).
 113   void ResetBirthTime();
 114
 115   bool MissingBirthPlace() const;
 116
 117 #if defined(TRACK_ALL_TASK_OBJECTS)
 118   base::TimeTicks tracked_birth_time() const { return tracked_birth_time_; }
 119 #else
 120   base::TimeTicks tracked_birth_time() const { return base::TimeTicks::Now(); }
 121 #endif  // defined(TRACK_ALL_TASK_OBJECTS)
 122
 123   // Returns null if SetBirthPlace has not been called.
 124   const void* get_birth_program_counter() const {
 125     return birth_program_counter_;
 126   }
 127
 128  private:
 129 #if defined(TRACK_ALL_TASK_OBJECTS)
 130
 131   // Pointer to instance were counts of objects with the same birth location
 132   // (on the same thread) are stored.
 133   Births* tracked_births_;
 134   // The time this object was constructed.  If its life consisted of a long
 135   // waiting period, and then it became active, then this value is generally
 136   // reset before the object begins it active life.
 137   base::TimeTicks tracked_birth_time_;
 138
 139 #endif  // defined(TRACK_ALL_TASK_OBJECTS)
 140
 141   const void* birth_program_counter_;
 142
 143   DISALLOW_COPY_AND_ASSIGN(Tracked);
 144 };
 145
 146 }  // namespace tracked_objects
 147
 148 #endif  // BASE_TRACKED_H_