diff options
author | Rich Trott <rtrott@gmail.com> | 2020-08-29 17:18:57 +0300 |
---|---|---|
committer | Rich Trott <rtrott@gmail.com> | 2020-09-01 05:51:08 +0300 |
commit | 51425a8725fe971b72b30d05c41b8c5d051eecfc (patch) | |
tree | 00add0ca9fd5b09fafb5f89de920825b458ed5ee /doc/api/perf_hooks.md | |
parent | 75d943ed4a51cee92d92f9bdd1e0c563bea583ae (diff) |
doc: arrange perf_hooks entries alphabetically
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 <deb2001-github@yahoo.de>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Harshitha K P <harshitha014@gmail.com>
Diffstat (limited to 'doc/api/perf_hooks.md')
-rw-r--r-- | doc/api/perf_hooks.md | 204 |
1 files changed, 102 insertions, 102 deletions
diff --git a/doc/api/perf_hooks.md b/doc/api/perf_hooks.md index c8770c25605..9f146838c72 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])` +<!-- YAML +added: REPLACEME +--> + +* `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. + +<!-- eslint-skip --> +```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])` <!-- YAML added: v8.5.0 @@ -165,62 +221,6 @@ obs.observe({ entryTypes: ['function'] }); wrapped(); ``` -### `performance.eventLoopUtilization([util1][,util2])` -<!-- YAML -added: REPLACEME ---> - -* `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. - -<!-- eslint-skip --> -```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` <!-- YAML added: v8.5.0 @@ -236,41 +236,54 @@ added: v8.5.0 The total number of milliseconds elapsed for this entry. This value will not be meaningful for all Performance Entry types. -### `performanceEntry.name` +### `performanceEntry.entryType` <!-- YAML added: v8.5.0 --> * {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 <!-- YAML -added: v8.5.0 +added: + - v13.9.0 + - v12.17.0 --> * {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` <!-- YAML added: v8.5.0 --> * {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` <!-- YAML @@ -290,28 +303,15 @@ The value may be one of: * `perf_hooks.constants.NODE_PERFORMANCE_GC_INCREMENTAL` * `perf_hooks.constants.NODE_PERFORMANCE_GC_WEAKCB` -### performanceEntry.flags +### `performanceEntry.startTime` <!-- YAML -added: - - v13.9.0 - - v12.17.0 +added: v8.5.0 --> * {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` <!-- YAML @@ -346,6 +346,19 @@ added: v8.5.0 The high resolution millisecond timestamp at which the Node.js environment was initialized. +### `performanceNodeTiming.idleTime` +<!-- YAML +added: REPLACEME +--> + +* {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` <!-- YAML added: v8.5.0 @@ -388,19 +401,6 @@ added: v8.5.0 The high resolution millisecond timestamp at which the V8 platform was initialized. -### `performanceNodeTiming.idleTime` -<!-- YAML -added: REPLACEME ---> - -* {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)` |