js/public/AllocationRecording.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*-
   2  * vim: set ts=8 sts=2 et sw=2 tw=80:
   3  * This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #ifndef js_AllocationRecording_h
   8 #define js_AllocationRecording_h
   9
  10 #include <stdint.h>
  11 #include "jstypes.h"
  12 #include "js/TypeDecls.h"
  13
  14 namespace JS {
  15
  16 /**
  17  * This struct holds the information needed to create a profiler marker payload
  18  * that can represent a JS allocation. It translates JS engine specific classes,
  19  * into something that can be used in the profiler.
  20  */
  21 struct RecordAllocationInfo {
  22   RecordAllocationInfo(const char16_t* typeName, const char* className,
  23                        const char16_t* descriptiveTypeName,
  24                        const char* coarseType, uint64_t size, bool inNursery)
  25       : typeName(typeName),
  26         className(className),
  27         descriptiveTypeName(descriptiveTypeName),
  28         coarseType(coarseType),
  29         size(size),
  30         inNursery(inNursery) {}
  31
  32   // These pointers are borrowed from the UbiNode, and can point to live data.
  33   // It is important for the consumers of this struct to correctly
  34   // duplicate the strings to take ownership of them.
  35   const char16_t* typeName;
  36   const char* className;
  37   const char16_t* descriptiveTypeName;
  38
  39   // The coarseType points to a string literal, so does not need to be
  40   // duplicated.
  41   const char* coarseType;
  42
  43   // The size in bytes of the allocation.
  44   uint64_t size;
  45
  46   // Whether or not the allocation is in the nursery or not.
  47   bool inNursery;
  48 };
  49
  50 typedef void (*RecordAllocationsCallback)(RecordAllocationInfo&& info);
  51
  52 /**
  53  * Enable recording JS allocations. This feature hooks into the object creation
  54  * in the JavaScript engine, and reports back the allocation info through the
  55  * callback. This allocation tracking is turned on for all encountered realms.
  56  * The JS Debugger API can also turn on allocation tracking with its own
  57  * probability. If both allocation tracking mechanisms are turned on at the same
  58  * time, the Debugger's probability defers to the EnableRecordingAllocations's
  59  * probability setting.
  60  */
  61 JS_PUBLIC_API void EnableRecordingAllocations(
  62     JSContext* cx, RecordAllocationsCallback callback, double probability);
  63
  64 /**
  65  * Turn off JS allocation recording. If any JS Debuggers are also recording
  66  * allocations, then the probability will be reset to the Debugger's desired
  67  * setting.
  68  */
  69 JS_PUBLIC_API void DisableRecordingAllocations(JSContext* cx);
  70
  71 }  // namespace JS
  72
  73 #endif /* js_AllocationRecording_h */