1 /*
2  * Copyright 2015 Google Inc.
3  *
4  * Use of this source code is governed by a BSD-style license that can be
5  * found in the LICENSE file.
6  */
7 
8 #ifndef SkTraceMemoryDump_DEFINED
9 #define SkTraceMemoryDump_DEFINED
10 
11 #include "include/core/SkTypes.h"
12 
13 class SkDiscardableMemory;
14 
15 /**
16  * Interface for memory tracing.
17  * This interface is meant to be passed as argument to the memory dump methods of Skia objects.
18  * The implementation of this interface is provided by the embedder.
19  */
20 class SK_API SkTraceMemoryDump {
21 public:
22     /**
23      * Enum to specify the level of the requested details for the dump from the Skia objects.
24      */
25     enum LevelOfDetail {
26         // Dump only the minimal details to get the total memory usage (Usually just the totals).
27         kLight_LevelOfDetail,
28 
29         // Dump the detailed breakdown of the objects in the caches.
30         kObjectsBreakdowns_LevelOfDetail
31     };
32 
33     /**
34      *  Appends a new memory dump (i.e. a row) to the trace memory infrastructure.
35      *  If dumpName does not exist yet, a new one is created. Otherwise, a new column is appended to
36      *  the previously created dump.
37      *  Arguments:
38      *    dumpName: an absolute, slash-separated, name for the item being dumped
39      *        e.g., "skia/CacheX/EntryY".
40      *    valueName: a string indicating the name of the column.
41      *        e.g., "size", "active_size", "number_of_objects".
42      *        This string is supposed to be long lived and is NOT copied.
43      *    units: a string indicating the units for the value.
44      *        e.g., "bytes", "objects".
45      *        This string is supposed to be long lived and is NOT copied.
46      *    value: the actual value being dumped.
47      */
48     virtual void dumpNumericValue(const char* dumpName,
49                                   const char* valueName,
50                                   const char* units,
51                                   uint64_t value) = 0;
52 
dumpStringValue(const char *,const char *,const char *)53     virtual void dumpStringValue(const char* /*dumpName*/,
54                                  const char* /*valueName*/,
55                                  const char* /*value*/) { }
56 
57     /**
58      * Sets the memory backing for an existing dump.
59      * backingType and backingObjectId are used by the embedder to associate the memory dumped via
60      * dumpNumericValue with the corresponding dump that backs the memory.
61      */
62     virtual void setMemoryBacking(const char* dumpName,
63                                   const char* backingType,
64                                   const char* backingObjectId) = 0;
65 
66     /**
67      * Specialization for memory backed by discardable memory.
68      */
69     virtual void setDiscardableMemoryBacking(
70         const char* dumpName,
71         const SkDiscardableMemory& discardableMemoryObject) = 0;
72 
73     /**
74      * Returns the type of details requested in the dump. The granularity of the dump is supposed to
75      * match the LevelOfDetail argument. The level of detail must not affect the total size
76      * reported, but only granularity of the child entries.
77      */
78     virtual LevelOfDetail getRequestedDetails() const = 0;
79 
80     /**
81      * Returns true if we should dump wrapped objects. Wrapped objects come from outside Skia, and
82      * may be independently tracked there.
83      */
shouldDumpWrappedObjects()84     virtual bool shouldDumpWrappedObjects() const { return true; }
85 
86 protected:
~SkTraceMemoryDump()87     virtual ~SkTraceMemoryDump() { }
88 };
89 
90 #endif
91