From 51425a8725fe971b72b30d05c41b8c5d051eecfc Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Sat, 29 Aug 2020 07:18:57 -0700 Subject: [PATCH] doc: arrange perf_hooks entries alphabetically MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Entries in perf_hooks.md are almost-but-not-quite in alphabetical order. Our docs (usually) list things in alphabetical order, so move a few entries to make it so in perf_hooks.md. PR-URL: https://github.com/nodejs/node/pull/34973 Reviewed-By: Gerhard Stöbich Reviewed-By: Luigi Pinca Reviewed-By: Harshitha K P --- doc/api/perf_hooks.md | 204 +++++++++++++++++++++--------------------- 1 file changed, 102 insertions(+), 102 deletions(-) diff --git a/doc/api/perf_hooks.md b/doc/api/perf_hooks.md index c8770c25605370..9f146838c72d29 100644 --- a/doc/api/perf_hooks.md +++ b/doc/api/perf_hooks.md @@ -53,6 +53,62 @@ added: v8.5.0 If `name` is not provided, removes all `PerformanceMark` objects from the Performance Timeline. If `name` is provided, removes only the named mark. +### `performance.eventLoopUtilization([util1][,util2])` + + +* `util1` {Object} The result of a previous call to `eventLoopUtilization()` +* `util2` {Object} The result of a previous call to `eventLoopUtilization()` + prior to `util1` +* Returns {Object} + * `idle` {number} + * `active` {number} + * `utilization` {number} + +The `eventLoopUtilization()` method returns an object that contains the +cumulative duration of time the event loop has been both idle and active as a +high resolution milliseconds timer. The `utilization` value is the calculated +Event Loop Utilization (ELU). If bootstrapping has not yet finished, the +properties have the value of 0. + +`util1` and `util2` are optional parameters. + +If `util1` is passed then the delta between the current call's `active` and +`idle` times are calculated and returned (similar to [`process.hrtime()`][]). +Likewise the adjusted `utilization` value is calculated. + +If `util1` and `util2` are both passed then the calculation adjustments are +done between the two arguments. This is a convenience option because unlike +[`process.hrtime()`][] additional work is done to calculate the ELU. + +ELU is similar to CPU utilization except that it is calculated using high +precision wall-clock time. It represents the percentage of time the event loop +has spent outside the event loop's event provider (e.g. `epoll_wait`). No other +CPU idle time is taken into consideration. The following is an example of how +a mostly idle process will have a high ELU. + + +```js +'use strict'; +const { eventLoopUtilization } = require('perf_hooks').performance; +const { spawnSync } = require('child_process'); + +setImmediate(() => { + const elu = eventLoopUtilization(); + spawnSync('sleep', ['5']); + console.log(eventLoopUtilization(elu).utilization); +}); +``` + +While the CPU is mostly idle while running this script the value of +`utilization` is 1. This is because the call to [`child_process.spawnSync()`][] +blocks the event loop from proceeding. + +Passing in a user-defined object instead of the result of a previous call to +`eventLoopUtilization()` will lead to undefined behavior. The return values +are not guaranteed to reflect any correct state of the event loop. + ### `performance.mark([name])` - -* `util1` {Object} The result of a previous call to `eventLoopUtilization()` -* `util2` {Object} The result of a previous call to `eventLoopUtilization()` - prior to `util1` -* Returns {Object} - * `idle` {number} - * `active` {number} - * `utilization` {number} - -The `eventLoopUtilization()` method returns an object that contains the -cumulative duration of time the event loop has been both idle and active as a -high resolution milliseconds timer. The `utilization` value is the calculated -Event Loop Utilization (ELU). If bootstrapping has not yet finished, the -properties have the value of 0. - -`util1` and `util2` are optional parameters. - -If `util1` is passed then the delta between the current call's `active` and -`idle` times are calculated and returned (similar to [`process.hrtime()`][]). -Likewise the adjusted `utilization` value is calculated. - -If `util1` and `util2` are both passed then the calculation adjustments are -done between the two arguments. This is a convenience option because unlike -[`process.hrtime()`][] additional work is done to calculate the ELU. - -ELU is similar to CPU utilization except that it is calculated using high -precision wall-clock time. It represents the percentage of time the event loop -has spent outside the event loop's event provider (e.g. `epoll_wait`). No other -CPU idle time is taken into consideration. The following is an example of how -a mostly idle process will have a high ELU. - - -```js -'use strict'; -const { eventLoopUtilization } = require('perf_hooks').performance; -const { spawnSync } = require('child_process'); - -setImmediate(() => { - const elu = eventLoopUtilization(); - spawnSync('sleep', ['5']); - console.log(eventLoopUtilization(elu).utilization); -}); -``` - -While the CPU is mostly idle while running this script the value of -`utilization` is 1. This is because the call to [`child_process.spawnSync()`][] -blocks the event loop from proceeding. - -Passing in a user-defined object instead of the result of a previous call to -`eventLoopUtilization()` will lead to undefined behavior. The return values -are not guaranteed to reflect any correct state of the event loop. - ## Class: `PerformanceEntry` * {string} -The name of the performance entry. +The type of the performance entry. It may be one of: -### `performanceEntry.startTime` +* `'node'` (Node.js only) +* `'mark'` (available on the Web) +* `'measure'` (available on the Web) +* `'gc'` (Node.js only) +* `'function'` (Node.js only) +* `'http2'` (Node.js only) +* `'http'` (Node.js only) + +### performanceEntry.flags * {number} -The high resolution millisecond timestamp marking the starting time of the -Performance Entry. +_This property is an extension by Node.js. It is not available in Web browsers._ -### `performanceEntry.entryType` +When `performanceEntry.entryType` is equal to `'gc'`, the `performance.flags` +property contains additional information about garbage collection operation. +The value may be one of: + +* `perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_NO` +* `perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_CONSTRUCT_RETAINED` +* `perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_FORCED` +* `perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_SYNCHRONOUS_PHANTOM_PROCESSING` +* `perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_ALL_AVAILABLE_GARBAGE` +* `perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_ALL_EXTERNAL_MEMORY` +* `perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_SCHEDULE_IDLE` + +### `performanceEntry.name` * {string} -The type of the performance entry. It may be one of: - -* `'node'` (Node.js only) -* `'mark'` (available on the Web) -* `'measure'` (available on the Web) -* `'gc'` (Node.js only) -* `'function'` (Node.js only) -* `'http2'` (Node.js only) -* `'http'` (Node.js only) +The name of the performance entry. ### `performanceEntry.kind` * {number} -_This property is an extension by Node.js. It is not available in Web browsers._ - -When `performanceEntry.entryType` is equal to `'gc'`, the `performance.flags` -property contains additional information about garbage collection operation. -The value may be one of: - -* `perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_NO` -* `perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_CONSTRUCT_RETAINED` -* `perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_FORCED` -* `perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_SYNCHRONOUS_PHANTOM_PROCESSING` -* `perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_ALL_AVAILABLE_GARBAGE` -* `perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_ALL_EXTERNAL_MEMORY` -* `perf_hooks.constants.NODE_PERFORMANCE_GC_FLAGS_SCHEDULE_IDLE` +The high resolution millisecond timestamp marking the starting time of the +Performance Entry. ## Class: `PerformanceNodeTiming` + +* {number} + +The high resolution millisecond timestamp of the amount of time the event loop +has been idle within the event loop's event provider (e.g. `epoll_wait`). This +does not take CPU usage into consideration. If the event loop has not yet +started (e.g., in the first tick of the main script), the property has the +value of 0. + ### `performanceNodeTiming.loopExit` - -* {number} - -The high resolution millisecond timestamp of the amount of time the event loop -has been idle within the event loop's event provider (e.g. `epoll_wait`). This -does not take CPU usage into consideration. If the event loop has not yet -started (e.g., in the first tick of the main script), the property has the -value of 0. - ## Class: `perf_hooks.PerformanceObserver` ### `new PerformanceObserver(callback)`