Skip to content

Commit

Permalink
src: add JSDoc typings for v8
Browse files Browse the repository at this point in the history
Added JSDoc typings for the `v8` lib module.

PR-URL: #38944
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Michael Dawson <midawson@redhat.com>
Reviewed-By: Zijian Liu <lxxyxzj@gmail.com>
  • Loading branch information
VoltrexKeyva authored and targos committed Sep 4, 2021
1 parent a4d70ff commit 41213bd
Showing 1 changed file with 78 additions and 0 deletions.
78 changes: 78 additions & 0 deletions lib/v8.js
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,12 @@ const {
} = internalBinding('heap_utils');
const { HeapSnapshotStream } = require('internal/heap_utils');

/**
* Generates a snapshot of the current V8 heap
* and writes it to a JSON file.
* @param {string} [filename]
* @returns {string}
*/
function writeHeapSnapshot(filename) {
if (filename !== undefined) {
filename = getValidatedPath(filename);
Expand All @@ -66,6 +72,11 @@ function writeHeapSnapshot(filename) {
return triggerHeapSnapshot(filename);
}

/**
* Generates a snapshot of the current V8 heap
* and returns a Readable Stream.
* @returns {import('./stream.js').Readable}
*/
function getHeapSnapshot() {
const handle = createHeapSnapshotStream();
assert(handle);
Expand Down Expand Up @@ -110,11 +121,32 @@ const {

const kNumberOfHeapSpaces = kHeapSpaces.length;

/**
* Sets V8 command-line flags.
* @param {string} flags
* @returns {void}
*/
function setFlagsFromString(flags) {
validateString(flags, 'flags');
_setFlagsFromString(flags);
}

/**
* Gets the current V8 heap statistics.
* @returns {{
* total_heap_size: number;
* total_heap_size_executable: number;
* total_physical_size: number;
* total_available_size: number;
* used_heap_size: number;
* heap_size_limit: number;
* malloced_memory: number;
* peak_malloced_memory: number;
* does_zap_garbage: number;
* number_of_native_contexts: number;
* number_of_detached_contexts: number;
* }}
*/
function getHeapStatistics() {
const buffer = heapStatisticsBuffer;

Expand All @@ -135,6 +167,16 @@ function getHeapStatistics() {
};
}

/**
* Gets the current V8 heap space statistics.
* @returns {{
* space_name: string;
* space_size: number;
* space_used_size: number;
* space_available_size: number;
* physical_space_size: number;
* }[]}
*/
function getHeapSpaceStatistics() {
const heapSpaceStatistics = new Array(kNumberOfHeapSpaces);
const buffer = heapSpaceStatisticsBuffer;
Expand All @@ -153,6 +195,14 @@ function getHeapSpaceStatistics() {
return heapSpaceStatistics;
}

/**
* Gets the current V8 heap code statistics.
* @returns {{
* code_and_metadata_size: number;
* bytecode_and_metadata_size: number;
* external_script_source_size: number;
* }}
*/
function getHeapCodeStatistics() {
const buffer = heapCodeStatisticsBuffer;

Expand All @@ -169,6 +219,11 @@ function getHeapCodeStatistics() {
/* JS methods for the base objects */
Serializer.prototype._getDataCloneError = Error;

/**
* Reads raw bytes from the deserializer's internal buffer.
* @param {number} length
* @returns {Buffer}
*/
Deserializer.prototype.readRawBytes = function readRawBytes(length) {
const offset = this._readRawBytes(length);
// `this.buffer` can be a Buffer or a plain Uint8Array, so just calling
Expand Down Expand Up @@ -209,6 +264,12 @@ class DefaultSerializer extends Serializer {
this._setTreatArrayBufferViewsAsHostObjects(true);
}

/**
* Used to write some kind of host object, i.e. an
* object that is created by native C++ bindings.
* @param {Object} abView
* @returns {void}
*/
_writeHostObject(abView) {
let i = 0;
if (abView.constructor === Buffer) {
Expand All @@ -231,6 +292,11 @@ class DefaultSerializer extends Serializer {
}

class DefaultDeserializer extends Deserializer {
/**
* Used to read some kind of host object, i.e. an
* object that is created by native C++ bindings.
* @returns {any}
*/
_readHostObject() {
const typeIndex = this.readUint32();
const ctor = arrayBufferViewTypes[typeIndex];
Expand All @@ -253,13 +319,25 @@ class DefaultDeserializer extends Deserializer {
}
}

/**
* Uses a `DefaultSerializer` to serialize `value`
* into a buffer.
* @param {any} value
* @returns {Buffer}
*/
function serialize(value) {
const ser = new DefaultSerializer();
ser.writeHeader();
ser.writeValue(value);
return ser.releaseBuffer();
}

/**
* Uses a `DefaultDeserializer` with default options
* to read a JavaScript value from a buffer.
* @param {Buffer | TypedArray | DataView} buffer
* @returns {any}
*/
function deserialize(buffer) {
const der = new DefaultDeserializer(buffer);
der.readHeader();
Expand Down

0 comments on commit 41213bd

Please sign in to comment.