Use UintToString() for unsigned values.
[chromium-blink-merge.git] / base / trace_event / memory_dump_manager.h
blobb445cdb7fc60fa1cd41150e2189eba04053a910c
1 // Copyright 2015 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.
5 #ifndef BASE_TRACE_EVENT_MEMORY_DUMP_MANAGER_H_
6 #define BASE_TRACE_EVENT_MEMORY_DUMP_MANAGER_H_
8 #include <set>
10 #include "base/atomicops.h"
11 #include "base/containers/hash_tables.h"
12 #include "base/memory/ref_counted.h"
13 #include "base/memory/singleton.h"
14 #include "base/synchronization/lock.h"
15 #include "base/timer/timer.h"
16 #include "base/trace_event/memory_dump_request_args.h"
17 #include "base/trace_event/process_memory_dump.h"
18 #include "base/trace_event/trace_event.h"
20 namespace base {
22 class SingleThreadTaskRunner;
24 namespace trace_event {
26 class MemoryDumpManagerDelegate;
27 class MemoryDumpProvider;
28 class MemoryDumpSessionState;
30 // This is the interface exposed to the rest of the codebase to deal with
31 // memory tracing. The main entry point for clients is represented by
32 // RequestDumpPoint(). The extension by Un(RegisterDumpProvider).
33 class BASE_EXPORT MemoryDumpManager : public TraceLog::EnabledStateObserver {
34 public:
35 static const char* const kTraceCategory;
37 // This value is returned as the tracing id of the child processes by
38 // GetTracingProcessId() when tracing is not enabled.
39 static const uint64 kInvalidTracingProcessId;
41 static MemoryDumpManager* GetInstance();
43 // Invoked once per process to listen to trace begin / end events.
44 // Initialization can happen after (Un)RegisterMemoryDumpProvider() calls
45 // and the MemoryDumpManager guarantees to support this.
46 // On the other side, the MemoryDumpManager will not be fully operational
47 // (i.e. will NACK any RequestGlobalMemoryDump()) until initialized.
48 // Arguments:
49 // is_coordinator: if true this MemoryDumpManager instance will act as a
50 // coordinator and schedule periodic dumps (if enabled via TraceConfig);
51 // false when the MemoryDumpManager is initialized in a slave process.
52 // delegate: inversion-of-control interface for embedder-specific behaviors
53 // (multiprocess handshaking). See the lifetime and thread-safety
54 // requirements in the |MemoryDumpManagerDelegate| docstring.
55 void Initialize(MemoryDumpManagerDelegate* delegate, bool is_coordinator);
57 // MemoryDumpManager does NOT take memory ownership of |mdp|, which is
58 // expected to either be a singleton or unregister itself.
59 // If the optional |task_runner| argument is non-null, all the calls to the
60 // |mdp| will be issues on the given thread. Otherwise, the |mdp| should be
61 // able to handle calls on arbitrary threads.
62 void RegisterDumpProvider(
63 MemoryDumpProvider* mdp,
64 const scoped_refptr<SingleThreadTaskRunner>& task_runner);
65 void RegisterDumpProvider(MemoryDumpProvider* mdp);
66 void UnregisterDumpProvider(MemoryDumpProvider* mdp);
68 // Requests a memory dump. The dump might happen or not depending on the
69 // filters and categories specified when enabling tracing.
70 // The optional |callback| is executed asynchronously, on an arbitrary thread,
71 // to notify about the completion of the global dump (i.e. after all the
72 // processes have dumped) and its success (true iff all the dumps were
73 // successful).
74 void RequestGlobalDump(MemoryDumpType dump_type,
75 MemoryDumpLevelOfDetail level_of_detail,
76 const MemoryDumpCallback& callback);
78 // Same as above (still asynchronous), but without callback.
79 void RequestGlobalDump(MemoryDumpType dump_type,
80 MemoryDumpLevelOfDetail level_of_detail);
82 // TraceLog::EnabledStateObserver implementation.
83 void OnTraceLogEnabled() override;
84 void OnTraceLogDisabled() override;
86 // Returns the MemoryDumpSessionState object, which is shared by all the
87 // ProcessMemoryDump and MemoryAllocatorDump instances through all the tracing
88 // session lifetime.
89 const scoped_refptr<MemoryDumpSessionState>& session_state() const {
90 return session_state_;
93 // Returns a unique id for identifying the processes. The id can be
94 // retrieved by child processes only when tracing is enabled. This is
95 // intended to express cross-process sharing of memory dumps on the
96 // child-process side, without having to know its own child process id.
97 uint64 GetTracingProcessId() const;
99 // Returns the name for a the allocated_objects dump. Use this to declare
100 // suballocator dumps from other dump providers.
101 // It will return nullptr if there is no dump provider for the system
102 // allocator registered (which is currently the case for Mac OS).
103 const char* system_allocator_pool_name() const {
104 return kSystemAllocatorPoolName;
107 private:
108 friend struct DefaultDeleter<MemoryDumpManager>; // For the testing instance.
109 friend struct DefaultSingletonTraits<MemoryDumpManager>;
110 friend class MemoryDumpManagerDelegate;
111 friend class MemoryDumpManagerTest;
113 // Descriptor struct used to hold information about registered MDPs. It is
114 // deliberately copyable, in order to allow it to be used as std::set value.
115 struct MemoryDumpProviderInfo {
116 MemoryDumpProviderInfo(
117 MemoryDumpProvider* dump_provider,
118 const scoped_refptr<SingleThreadTaskRunner>& task_runner);
119 ~MemoryDumpProviderInfo();
121 // Define a total order based on the thread (i.e. |task_runner|) affinity,
122 // so that all MDP belonging to the same thread are adjacent in the set.
123 bool operator<(const MemoryDumpProviderInfo& other) const;
125 MemoryDumpProvider* const dump_provider;
126 scoped_refptr<SingleThreadTaskRunner> task_runner; // Optional.
128 // For fail-safe logic (auto-disable failing MDPs). These fields are mutable
129 // as can be safely changed without impacting the order within the set.
130 mutable int consecutive_failures;
131 mutable bool disabled;
133 // When a dump provider unregisters, it is flagged as |unregistered| and it
134 // is removed only upon the next memory dump. This is to avoid altering the
135 // |dump_providers_| collection while a dump is in progress.
136 mutable bool unregistered;
139 using MemoryDumpProviderInfoSet = std::set<MemoryDumpProviderInfo>;
141 // Holds the state of a process memory dump that needs to be carried over
142 // across threads in order to fulfil an asynchronous CreateProcessDump()
143 // request. At any time exactly one thread owns a ProcessMemoryDumpAsyncState.
144 struct ProcessMemoryDumpAsyncState {
145 ProcessMemoryDumpAsyncState(
146 MemoryDumpRequestArgs req_args,
147 MemoryDumpProviderInfoSet::iterator next_dump_provider,
148 const scoped_refptr<MemoryDumpSessionState>& session_state,
149 MemoryDumpCallback callback);
150 ~ProcessMemoryDumpAsyncState();
152 // The ProcessMemoryDump container, where each dump provider will dump its
153 // own MemoryAllocatorDump(s) upon the OnMemoryDump() call.
154 ProcessMemoryDump process_memory_dump;
156 // The arguments passed to the initial CreateProcessDump() request.
157 const MemoryDumpRequestArgs req_args;
159 // The |dump_providers_| iterator to the next dump provider that should be
160 // invoked (or dump_providers_.end() if at the end of the sequence).
161 MemoryDumpProviderInfoSet::iterator next_dump_provider;
163 // Callback passed to the initial call to CreateProcessDump().
164 MemoryDumpCallback callback;
166 // The thread on which FinalizeDumpAndAddToTrace() (and hence |callback|)
167 // should be invoked. This is the thread on which the initial
168 // CreateProcessDump() request was called.
169 const scoped_refptr<SingleThreadTaskRunner> task_runner;
171 private:
172 DISALLOW_COPY_AND_ASSIGN(ProcessMemoryDumpAsyncState);
175 static const int kMaxConsecutiveFailuresCount;
176 static const char* const kSystemAllocatorPoolName;
178 MemoryDumpManager();
179 ~MemoryDumpManager() override;
181 static void SetInstanceForTesting(MemoryDumpManager* instance);
182 static void FinalizeDumpAndAddToTrace(
183 scoped_ptr<ProcessMemoryDumpAsyncState> pmd_async_state);
184 static void AbortDumpLocked(MemoryDumpCallback callback,
185 scoped_refptr<SingleThreadTaskRunner> task_runner,
186 uint64 dump_guid);
188 // Internal, used only by MemoryDumpManagerDelegate.
189 // Creates a memory dump for the current process and appends it to the trace.
190 // |callback| will be invoked asynchronously upon completion on the same
191 // thread on which CreateProcessDump() was called.
192 void CreateProcessDump(const MemoryDumpRequestArgs& args,
193 const MemoryDumpCallback& callback);
195 // Continues the ProcessMemoryDump started by CreateProcessDump(), hopping
196 // across threads as needed as specified by MDPs in RegisterDumpProvider().
197 void ContinueAsyncProcessDump(
198 scoped_ptr<ProcessMemoryDumpAsyncState> pmd_async_state);
200 // An ordererd set of registered MemoryDumpProviderInfo(s), sorted by thread
201 // affinity (MDPs belonging to the same thread are adjacent).
202 MemoryDumpProviderInfoSet dump_providers_;
204 // Shared among all the PMDs to keep state scoped to the tracing session.
205 scoped_refptr<MemoryDumpSessionState> session_state_;
207 MemoryDumpManagerDelegate* delegate_; // Not owned.
209 // When true, this instance is in charge of coordinating periodic dumps.
210 bool is_coordinator_;
212 // Protects from concurrent accesses to the |dump_providers_*| and |delegate_|
213 // to guard against disabling logging while dumping on another thread.
214 Lock lock_;
216 // Optimization to avoid attempting any memory dump (i.e. to not walk an empty
217 // dump_providers_enabled_ list) when tracing is not enabled.
218 subtle::AtomicWord memory_tracing_enabled_;
220 // For time-triggered periodic dumps.
221 RepeatingTimer<MemoryDumpManager> periodic_dump_timer_;
223 // The unique id of the child process. This is created only for tracing and is
224 // expected to be valid only when tracing is enabled.
225 uint64 tracing_process_id_;
227 // Skips the auto-registration of the core dumpers during Initialize().
228 bool skip_core_dumpers_auto_registration_for_testing_;
230 DISALLOW_COPY_AND_ASSIGN(MemoryDumpManager);
233 // The delegate is supposed to be long lived (read: a Singleton) and thread
234 // safe (i.e. should expect calls from any thread and handle thread hopping).
235 class BASE_EXPORT MemoryDumpManagerDelegate {
236 public:
237 virtual void RequestGlobalMemoryDump(const MemoryDumpRequestArgs& args,
238 const MemoryDumpCallback& callback) = 0;
240 // Returns tracing process id of the current process. This is used by
241 // MemoryDumpManager::GetTracingProcessId.
242 virtual uint64 GetTracingProcessId() const = 0;
244 protected:
245 MemoryDumpManagerDelegate() {}
246 virtual ~MemoryDumpManagerDelegate() {}
248 void CreateProcessDump(const MemoryDumpRequestArgs& args,
249 const MemoryDumpCallback& callback) {
250 MemoryDumpManager::GetInstance()->CreateProcessDump(args, callback);
253 private:
254 DISALLOW_COPY_AND_ASSIGN(MemoryDumpManagerDelegate);
257 } // namespace trace_event
258 } // namespace base
260 #endif // BASE_TRACE_EVENT_MEMORY_DUMP_MANAGER_H_