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
13class 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 */
20class SK_API SkTraceMemoryDump {
21public:
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
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 */
84 virtual bool shouldDumpWrappedObjects() const { return true; }
85
86protected:
87 virtual ~SkTraceMemoryDump() { }
88};
89
90#endif
91