tracked.h revision c407dc5cd9bdc5668497f21b26b09d988ab439de 
1// Copyright (c) 2006-2008 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
21#include <string>
22
23#include "base/time.h"
24
25#ifndef NDEBUG
26#ifndef TRACK_ALL_TASK_OBJECTS
27#define TRACK_ALL_TASK_OBJECTS
28#endif   // TRACK_ALL_TASK_OBJECTS
29#endif  // NDEBUG
30
31namespace tracked_objects {
32
33//------------------------------------------------------------------------------
34// Location provides basic info where of an object was constructed, or was
35// significantly brought to life.
36
37class Location {
38 public:
39  // Constructor should be called with a long-lived char*, such as __FILE__.
40  // It assumes the provided value will persist as a global constant, and it
41  // will not make a copy of it.
42  Location(const char* function_name, const char* file_name, int line_number);
43
44  // Provide a default constructor for easy of debugging.
45  Location();
46
47  // Comparison operator for insertion into a std::map<> hash tables.
48  // All we need is *some* (any) hashing distinction.  Strings should already
49  // be unique, so we don't bother with strcmp or such.
50  // Use line number as the primary key (because it is fast, and usually gets us
51  // a difference), and then pointers as secondary keys (just to get some
52  // distinctions).
53  bool operator < (const Location& other) const {
54    if (line_number_ != other.line_number_)
55      return line_number_ < other.line_number_;
56    if (file_name_ != other.file_name_)
57      return file_name_ < other.file_name_;
58    return function_name_ < other.function_name_;
59  }
60
61  const char* function_name() const { return function_name_; }
62  const char* file_name()     const { return file_name_; }
63  int line_number()           const { return line_number_; }
64
65  void Write(bool display_filename, bool display_function_name,
66             std::string* output) const;
67
68  // Write function_name_ in HTML with '<' and '>' properly encoded.
69  void WriteFunctionName(std::string* output) const;
70
71 private:
72  const char* const function_name_;
73  const char* const file_name_;
74  const int line_number_;
75};
76
77
78//------------------------------------------------------------------------------
79// Define a macro to record the current source location.
80
81#define FROM_HERE tracked_objects::Location(__FUNCTION__, __FILE__, __LINE__)
82
83
84//------------------------------------------------------------------------------
85
86
87class Births;
88
89class Tracked {
90 public:
91  Tracked();
92  virtual ~Tracked();
93
94  // Used to record the FROM_HERE location of a caller.
95  void SetBirthPlace(const Location& from_here);
96
97  // When a task sits around a long time, such as in a timer, or object watcher,
98  // this method should be called when the task becomes active, and its
99  // significant lifetime begins (and its waiting to be woken up has passed).
100  void ResetBirthTime();
101
102  bool MissingBirthplace() const;
103
104#if defined(TRACK_ALL_TASK_OBJECTS)
105  base::TimeTicks tracked_birth_time() const { return tracked_birth_time_; }
106#else
107  base::TimeTicks tracked_birth_time() const { return base::TimeTicks::Now(); }
108#endif  // defined(TRACK_ALL_TASK_OBJECTS)
109
110 private:
111#if defined(TRACK_ALL_TASK_OBJECTS)
112
113  // Pointer to instance were counts of objects with the same birth location
114  // (on the same thread) are stored.
115  Births* tracked_births_;
116  // The time this object was constructed.  If its life consisted of a long
117  // waiting period, and then it became active, then this value is generally
118  // reset before the object begins it active life.
119  base::TimeTicks tracked_birth_time_;
120
121#endif  // defined(TRACK_ALL_TASK_OBJECTS)
122
123  DISALLOW_COPY_AND_ASSIGN(Tracked);
124};
125
126}  // namespace tracked_objects
127
128#endif  // BASE_TRACKED_H_
129