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 "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