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 
20 namespace base {
21 namespace trace_event {
22 
23 class ProcessMemoryDump;
24 class TracedValue;
25 
26 // Data model for user-land memory allocator dumps.
27 class 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