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.
4
5#ifndef BASE_TRACE_EVENT_MEMORY_ALLOCATOR_DUMP_H_
6#define BASE_TRACE_EVENT_MEMORY_ALLOCATOR_DUMP_H_
7
8#include <stdint.h>
9
10#include <memory>
11#include <string>
12
13#include "base/base_export.h"
14#include "base/gtest_prod_util.h"
15#include "base/logging.h"
16#include "base/macros.h"
17#include "base/trace_event/memory_allocator_dump_guid.h"
18#include "base/values.h"
19
20namespace base {
21namespace trace_event {
22
23class ProcessMemoryDump;
24class TracedValue;
25
26// Data model for user-land memory allocator dumps.
27class BASE_EXPORT MemoryAllocatorDump {
28 public:
29  enum Flags {
30    DEFAULT = 0,
31
32    // A dump marked weak will be discarded by TraceViewer.
33    WEAK = 1 << 0,
34  };
35
36  // MemoryAllocatorDump is owned by ProcessMemoryDump.
37  MemoryAllocatorDump(const std::string& absolute_name,
38                      ProcessMemoryDump* process_memory_dump,
39                      const MemoryAllocatorDumpGuid& guid);
40  MemoryAllocatorDump(const std::string& absolute_name,
41                      ProcessMemoryDump* process_memory_dump);
42  ~MemoryAllocatorDump();
43
44  // Standard attribute |name|s for the AddScalar and AddString() methods.
45  static const char kNameSize[];          // To represent allocated space.
46  static const char kNameObjectCount[];   // To represent number of objects.
47
48  // Standard attribute |unit|s for the AddScalar and AddString() methods.
49  static const char kUnitsBytes[];    // Unit name to represent bytes.
50  static const char kUnitsObjects[];  // Unit name to represent #objects.
51
52  // Constants used only internally and by tests.
53  static const char kTypeScalar[];  // Type name for scalar attributes.
54  static const char kTypeString[];  // Type name for string attributes.
55
56  // Setters for scalar attributes. Some examples:
57  // - "size" column (all dumps are expected to have at least this one):
58  //     AddScalar(kNameSize, kUnitsBytes, 1234);
59  // - Some extra-column reporting internal details of the subsystem:
60  //    AddScalar("number_of_freelist_entires", kUnitsObjects, 42)
61  // - Other informational column (will not be auto-added in the UI)
62  //    AddScalarF("kittens_ratio", "ratio", 42.0f)
63  void AddScalar(const char* name, const char* units, uint64_t value);
64  void AddScalarF(const char* name, const char* units, double value);
65  void AddString(const char* name, const char* units, const std::string& value);
66
67  // Absolute name, unique within the scope of an entire ProcessMemoryDump.
68  const std::string& absolute_name() const { return absolute_name_; }
69
70  // Called at trace generation time to populate the TracedValue.
71  void AsValueInto(TracedValue* value) const;
72
73  // Use enum Flags to set values.
74  void set_flags(int flags) { flags_ |= flags; }
75  void clear_flags(int flags) { flags_ &= ~flags; }
76  int flags() { return flags_; }
77
78  // |guid| is an optional global dump identifier, unique across all processes
79  // within the scope of a global dump. It is only required when using the
80  // graph APIs (see TODO_method_name) to express retention / suballocation or
81  // cross process sharing. See crbug.com/492102 for design docs.
82  // Subsequent MemoryAllocatorDump(s) with the same |absolute_name| are
83  // expected to have the same guid.
84  const MemoryAllocatorDumpGuid& guid() const { return guid_; }
85
86  TracedValue* attributes_for_testing() const { return attributes_.get(); }
87
88 private:
89  // TODO(hjd): Transitional until we send the full PMD. See crbug.com/704203
90  friend class MemoryDumpManager;
91  FRIEND_TEST_ALL_PREFIXES(MemoryAllocatorDumpTest, GetSize);
92
93  // Get the size for this dump.
94  // The size is the value set with AddScalar(kNameSize, kUnitsBytes, size);
95  // TODO(hjd): Transitional until we send the full PMD. See crbug.com/704203
96  uint64_t GetSize() const { return size_; };
97
98  const std::string absolute_name_;
99  ProcessMemoryDump* const process_memory_dump_;  // Not owned (PMD owns this).
100  std::unique_ptr<TracedValue> attributes_;
101  MemoryAllocatorDumpGuid guid_;
102  int flags_;  // See enum Flags.
103  uint64_t size_;
104
105  // A local buffer for Sprintf conversion on fastpath. Avoids allocating
106  // temporary strings on each AddScalar() call.
107  std::string string_conversion_buffer_;
108
109  DISALLOW_COPY_AND_ASSIGN(MemoryAllocatorDump);
110};
111
112}  // namespace trace_event
113}  // namespace base
114
115#endif  // BASE_TRACE_EVENT_MEMORY_ALLOCATOR_DUMP_H_
116