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 "js/TypeDecls.h"
  11 #include "js/Utility.h"
  12
  13 namespace JS {
  14
  15 /**
  16  * This struct holds the information needed to create a profiler marker payload
  17  * that can represent a JS allocation. It translates JS engine specific classes,
  18  * into something that can be used in the profiler.
  19  */
  20 struct RecordAllocationInfo {
  21   RecordAllocationInfo(const char16_t* typeName, const char* className,
  22                        const char16_t* descriptiveTypeName,
  23                        const char* coarseType, uint64_t size, bool inNursery)
  24       : typeName(typeName),
  25         className(className),
  26         descriptiveTypeName(descriptiveTypeName),
  27         coarseType(coarseType),
  28         size(size),
  29         inNursery(inNursery) {}
  30
  31   // These pointers are borrowed from the UbiNode, and can point to live data.
  32   // It is important for the consumers of this struct to correctly
  33   // duplicate the strings to take ownership of them.
  34   const char16_t* typeName;
  35   const char* className;
  36   const char16_t* descriptiveTypeName;
  37
  38   // The coarseType points to a string literal, so does not need to be
  39   // duplicated.
  40   const char* coarseType;
  41
  42   // The size in bytes of the allocation.
  43   uint64_t size;
  44
  45   // Whether or not the allocation is in the nursery or not.
  46   bool inNursery;
  47 };
  48
  49 typedef void (*RecordAllocationsCallback)(RecordAllocationInfo&& info);
  50
  51 /**
  52  * Enable recording JS allocations. This feature hooks into the object creation
  53  * in the JavaScript engine, and reports back the allocation info through the
  54  * callback. This allocation tracking is turned on for all encountered realms.
  55  * The JS Debugger API can also turn on allocation tracking with its own
  56  * probability. If both allocation tracking mechanisms are turned on at the same
  57  * time, the Debugger's probability defers to the EnableRecordingAllocations's
  58  * probability setting.
  59  */
  60 JS_FRIEND_API void EnableRecordingAllocations(
  61     JSContext* cx, RecordAllocationsCallback callback, double probability);
  62
  63 /**
  64  * Turn off JS allocation recording. If any JS Debuggers are also recording
  65  * allocations, then the probability will be reset to the Debugger's desired
  66  * setting.
  67  */
  68 JS_FRIEND_API void DisableRecordingAllocations(JSContext* cx);
  69
  70 }  // namespace JS
  71
  72 #endif /* js_AllocationRecording_h */