node/cppgc/heap-statistics.h

0001 // Copyright 2021 the V8 project authors. All rights reserved.
0002 // Use of this source code is governed by a BSD-style license that can be
0003 // found in the LICENSE file.
0004
0005 #ifndef INCLUDE_CPPGC_HEAP_STATISTICS_H_
0006 #define INCLUDE_CPPGC_HEAP_STATISTICS_H_
0007
0008 #include <cstddef>
0009 #include <cstdint>
0010 #include <string>
0011 #include <vector>
0012
0013 namespace cppgc {
0014
0015 /**
0016  * `HeapStatistics` contains memory consumption and utilization statistics for a
0017  * cppgc heap.
0018  */
0019 struct HeapStatistics final {
0020   /**
0021    * Specifies the detail level of the heap statistics. Brief statistics contain
0022    * only the top-level allocated and used memory statistics for the entire
0023    * heap. Detailed statistics also contain a break down per space and page, as
0024    * well as freelist statistics and object type histograms. Note that used
0025    * memory reported by brief statistics and detailed statistics might differ
0026    * slightly.
0027    */
0028   enum DetailLevel : uint8_t {
0029     kBrief,
0030     kDetailed,
0031   };
0032
0033   /**
0034    * Object statistics for a single type.
0035    */
0036   struct ObjectStatsEntry {
0037     /**
0038      * Number of allocated bytes.
0039      */
0040     size_t allocated_bytes;
0041     /**
0042      * Number of allocated objects.
0043      */
0044     size_t object_count;
0045   };
0046
0047   /**
0048    * Page granularity statistics. For each page the statistics record the
0049    * allocated memory size and overall used memory size for the page.
0050    */
0051   struct PageStatistics {
0052     /** Overall committed amount of memory for the page. */
0053     size_t committed_size_bytes = 0;
0054     /** Resident amount of memory held by the page. */
0055     size_t resident_size_bytes = 0;
0056     /** Amount of memory actually used on the page. */
0057     size_t used_size_bytes = 0;
0058     /**
0059      * Statistics for object allocated on the page. If an object provides a
0060      * name by inheriting from NameProvider, its name will be recorded in the
0061      * statistics. Other objects, without an explicit name, are merged under a
0062      * single type unless the CPPGC_SUPPORTS_OBJECT_NAME build flag is enabled.
0063      */
0064     std::vector<ObjectStatsEntry> object_statistics;
0065   };
0066
0067   /**
0068    * Statistics of the freelist (used only in non-large object spaces). For
0069    * each bucket in the freelist the statistics record the bucket size, the
0070    * number of freelist entries in the bucket, and the overall allocated memory
0071    * consumed by these freelist entries.
0072    */
0073   struct FreeListStatistics {
0074     /** bucket sizes in the freelist. */
0075     std::vector<size_t> bucket_size;
0076     /** number of freelist entries per bucket. */
0077     std::vector<size_t> free_count;
0078     /** memory size consumed by freelist entries per size. */
0079     std::vector<size_t> free_size;
0080   };
0081
0082   /**
0083    * Space granularity statistics. For each space the statistics record the
0084    * space name, the amount of allocated memory and overall used memory for the
0085    * space. The statistics also contain statistics for each of the space's
0086    * pages, its freelist and the objects allocated on the space.
0087    */
0088   struct SpaceStatistics {
0089     /** The space name */
0090     std::string name;
0091     /** Overall committed amount of memory for the heap. */
0092     size_t committed_size_bytes = 0;
0093     /** Resident amount of memory held by the heap. */
0094     size_t resident_size_bytes = 0;
0095     /** Amount of memory actually used on the space. */
0096     size_t used_size_bytes = 0;
0097     /** Statistics for each of the pages in the space. */
0098     std::vector<PageStatistics> page_stats;
0099     /** Statistics for the freelist of the space. */
0100     FreeListStatistics free_list_stats;
0101   };
0102
0103   /** Overall committed amount of memory for the heap. */
0104   size_t committed_size_bytes = 0;
0105   /** Resident amount of memory held by the heap. */
0106   size_t resident_size_bytes = 0;
0107   /** Amount of memory actually used on the heap. */
0108   size_t used_size_bytes = 0;
0109   /** Memory retained in the page pool, not used directly by the heap. */
0110   size_t pooled_memory_size_bytes = 0;
0111   /** Detail level of this HeapStatistics. */
0112   DetailLevel detail_level;
0113
0114   /** Statistics for each of the spaces in the heap. Filled only when
0115    * `detail_level` is `DetailLevel::kDetailed`. */
0116   std::vector<SpaceStatistics> space_stats;
0117
0118   /**
0119    * Vector of `cppgc::GarbageCollected` type names.
0120    */
0121   std::vector<std::string> type_names;
0122 };
0123
0124 }  // namespace cppgc
0125
0126 #endif  // INCLUDE_CPPGC_HEAP_STATISTICS_H_