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