text: // Copyright 2015 The Chromium Authors. All rights reserved.
  // Use of this source code is governed by a BSD-style license that can be
  // found in the LICENSE file.
  
  #ifndef WebProcessMemoryDump_h
  #define WebProcessMemoryDump_h
  
  #include "base/gtest_prod_util.h"
  #include "base/macros.h"
  #include "base/trace_event/heap_profiler_allocation_context.h"
  #include "base/trace_event/memory_dump_request_args.h"
  #include "platform/PlatformExport.h"
  #include "platform/instrumentation/tracing/web_memory_allocator_dump.h"
  #include "wtf/HashMap.h"
  #include "wtf/text/WTFString.h"
  #include <map>
  #include <memory>
  #include <vector>
  
  class SkTraceMemoryDump;
  
  namespace base {
  class DiscardableMemory;
  namespace trace_event {
  class MemoryAllocatorDump;
  class ProcessMemoryDump;
  class TraceEventMemoryOverhead;
  }  // namespace base
  }  // namespace trace_event
  
  namespace skia {
  class SkiaTraceMemoryDumpImpl;
  }  // namespace skia
  
  namespace blink {
  
  // Used to specify the type of memory dump the WebProcessMemoryDump should
  // generate on dump requests.
  // TODO(hajimehoshi): Remove this and use base::trace_event::
  // MemoryDumpLevelOfDetail instead.
  enum class WebMemoryDumpLevelOfDetail { Background, Light, Detailed };
  
  // A container which holds all the dumps for the various allocators for a given
  // process. Embedders of WebMemoryDumpProvider are expected to populate a
  // WebProcessMemoryDump instance with the stats of their allocators.
  class PLATFORM_EXPORT WebProcessMemoryDump final {
   public:
    // Creates a standalone WebProcessMemoryDump, which owns the underlying
    // ProcessMemoryDump.
    WebProcessMemoryDump();
  
    // Wraps (without owning) an existing ProcessMemoryDump.
    explicit WebProcessMemoryDump(
        base::trace_event::MemoryDumpLevelOfDetail level_of_detail,
        base::trace_event::ProcessMemoryDump* process_memory_dump);
  
    ~WebProcessMemoryDump();
  
    // Creates a new MemoryAllocatorDump with the given name and returns the
    // empty object back to the caller. |absoluteName| uniquely identifies the
    // dump within the scope of a ProcessMemoryDump. It is possible to express
    // nesting by means of a slash-separated path naming (e.g.,
    // "allocator_name/arena_1/subheap_X").
    // |guid| is  an optional identifier, unique among all processes within the
    // scope of a global dump. This is only relevant when using
    // addOwnershipEdge(). If omitted, it will be automatically generated.
    blink::WebMemoryAllocatorDump* createMemoryAllocatorDump(
        const String& absolute_name);
    blink::WebMemoryAllocatorDump* createMemoryAllocatorDump(
        const String& absolute_name,
        blink::WebMemoryAllocatorDumpGuid guid);
  
    // Gets a previously created MemoryAllocatorDump given its name.
    blink::WebMemoryAllocatorDump* getMemoryAllocatorDump(
        const String& absolute_name) const;
  
    // Removes all the WebMemoryAllocatorDump(s) contained in this instance.
    // This WebProcessMemoryDump can be safely reused as if it was new once this
    // method returns.
    void clear();
  
    // Merges all WebMemoryAllocatorDump(s) contained in |other| inside this
    // WebProcessMemoryDump, transferring their ownership to this instance.
    // |other| will be an empty WebProcessMemoryDump after this method returns
    // and can be reused as if it was new.
    void takeAllDumpsFrom(blink::WebProcessMemoryDump* other);
  
    // Adds an ownership relationship between two MemoryAllocatorDump(s) with
    // the semantics: |source| owns |target|, and has the effect of attributing
    // the memory usage of |target| to |source|. |importance| is optional and
    // relevant only for the cases of co-ownership, where it acts as a z-index:
    // the owner with the highest importance will be attributed |target|'s
    // memory.
    void addOwnershipEdge(blink::WebMemoryAllocatorDumpGuid source,
                          blink::WebMemoryAllocatorDumpGuid target,
                          int importance);
    void addOwnershipEdge(blink::WebMemoryAllocatorDumpGuid source,
                          blink::WebMemoryAllocatorDumpGuid target);
  
    // Utility method to add a suballocation relationship with the following
    // semantics: |source| is suballocated from |target_node_name|.
    // This creates a child node of |target_node_name| and adds an ownership
    // edge between |source| and the new child node. As a result, the UI will
    // not account the memory of |source| in the target node.
    void addSuballocation(blink::WebMemoryAllocatorDumpGuid source,
                          const String& target_node_name);
  
    // Returns the SkTraceMemoryDump proxy interface that can be passed to Skia
    // to dump into this WebProcessMemoryDump. Multiple SkTraceMemoryDump
    // objects can be created using this method. The created dumpers are owned
    // by WebProcessMemoryDump and cannot outlive the WebProcessMemoryDump
    // object owning them. |dumpNamePrefix| is prefix appended to each dump
    // created by the SkTraceMemoryDump implementation, if the dump should be
    // placed under different namespace and not "skia".
    SkTraceMemoryDump* createDumpAdapterForSkia(const String& dump_name_prefix);
  
    const base::trace_event::ProcessMemoryDump* process_memory_dump() const {
      return process_memory_dump_;
    }
  
    blink::WebMemoryAllocatorDump* createDiscardableMemoryAllocatorDump(
        const std::string& name,
        base::DiscardableMemory* discardable);
  
    // Dumps heap memory usage. |allocatorName| is used as an absolute name for
    // base::trace_event::ProcessMemoryDump::DumpHeapUsage().
    void dumpHeapUsage(const base::hash_map<base::trace_event::AllocationContext,
                                            base::trace_event::AllocationMetrics>&
                           metrics_by_context,
                       base::trace_event::TraceEventMemoryOverhead& overhead,
                       const char* allocator_name);
  
   private:
    FRIEND_TEST_ALL_PREFIXES(WebProcessMemoryDumpTest, IntegrationTest);
  
    blink::WebMemoryAllocatorDump* createWebMemoryAllocatorDump(
        base::trace_event::MemoryAllocatorDump* memory_allocator_dump);
  
    // Only for the case of ProcessMemoryDump being owned (i.e. the default ctor).
    std::unique_ptr<base::trace_event::ProcessMemoryDump>
        owned_process_memory_dump_;
  
    // The underlying ProcessMemoryDump instance to which the
    // createMemoryAllocatorDump() calls will be proxied to.
    base::trace_event::ProcessMemoryDump* process_memory_dump_;  // Not owned.
  
    // TODO(ssid): Remove it once this information is added to ProcessMemoryDump.
    base::trace_event::MemoryDumpLevelOfDetail level_of_detail_;
  
    // Reverse index of MemoryAllocatorDump -> WebMemoryAllocatorDump wrapper.
    // By design WebMemoryDumpProvider(s) are not supposed to hold the pointer
    // to the WebProcessMemoryDump passed as argument of the onMemoryDump() call.
    // Those pointers are valid only within the scope of the call and can be
    // safely torn down once the WebProcessMemoryDump itself is destroyed.
    HashMap<base::trace_event::MemoryAllocatorDump*,
            std::unique_ptr<WebMemoryAllocatorDump>>
        memory_allocator_dumps_;
  
    // Stores SkTraceMemoryDump for the current ProcessMemoryDump.
    std::vector<std::unique_ptr<skia::SkiaTraceMemoryDumpImpl>>
        sk_trace_dump_list_;
  
    DISALLOW_COPY_AND_ASSIGN(WebProcessMemoryDump);
  };
  
  }  // namespace blink
  
  #endif  // WebProcessMemoryDump_h
  