diff options
author | Stephen Belanger <admin@stephenbelanger.com> | 2020-08-22 02:25:39 +0300 |
---|---|---|
committer | Node.js GitHub Bot <github-bot@iojs.org> | 2020-11-01 00:24:11 +0300 |
commit | c6c36c3da7187fca3a0f3f8348e764cba6d23099 (patch) | |
tree | 258662c208fb9c0f2f2c84bc3ed412ad1ce275bb /doc/api/diagnostics_channel.md | |
parent | 5dd344a2a8a70d8c3b6e570c00b72f03d2801a84 (diff) |
lib: create diagnostics_channel module
PR-URL: https://github.com/nodejs/node/pull/34895
Reviewed-By: Bryan English <bryan@bryanenglish.com>
Reviewed-By: Gerhard Stöbich <deb2001-github@yahoo.de>
Reviewed-By: Vladimir de Turckheim <vlad2t@hotmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Gabriel Schulhof <gabriel.schulhof@intel.com>
Reviewed-By: Michael Dawson <midawson@redhat.com>
Diffstat (limited to 'doc/api/diagnostics_channel.md')
-rw-r--r-- | doc/api/diagnostics_channel.md | 180 |
1 files changed, 180 insertions, 0 deletions
diff --git a/doc/api/diagnostics_channel.md b/doc/api/diagnostics_channel.md new file mode 100644 index 00000000000..2f78ea80f67 --- /dev/null +++ b/doc/api/diagnostics_channel.md @@ -0,0 +1,180 @@ +# Diagnostics Channel + +<!--introduced_in=REPLACEME--> + +> Stability: 1 - Experimental + +<!-- source_link=lib/diagnostics_channel.js --> + +The `diagnostics_channel` module provides an API to create named channels +to report arbitrary message data for diagnostics purposes. + +It can be accessed using: + +```js +const diagnostics_channel = require('diagnostics_channel'); +``` + +It is intended that a module writer wanting to report diagnostics messages +will create one or many top-level channels to report messages through. +Channels may also be acquired at runtime but it is not encouraged +due to the additional overhead of doing so. Channels may be exported for +convenience, but as long as the name is known it can be acquired anywhere. + +If you intend for your module to produce diagnostics data for others to +consume it is recommended that you include documentation of what named +channels are used along with the shape of the message data. Channel names +should generally include the module name to avoid collisions with data from +other modules. + +## Public API + +### Overview + +Following is a simple overview of the public API. + +```js +const diagnostics_channel = require('diagnostics_channel'); + +// Get a reusable channel object +const channel = diagnostics_channel.channel('my-channel'); + +// Subscribe to the channel +channel.subscribe((message, name) => { + // Received data +}); + +// Check if the channel has an active subscriber +if (channel.hasSubscribers) { + // Publish data to the channel + channel.publish({ + some: 'data' + }); +} +``` + +#### `diagnostics_channel.hasSubscribers(name)` + +* `name` {string|symbol} The channel name +* Returns: {boolean} If there are active subscribers + +Check if there are active subscribers to the named channel. This is helpful if +the message you want to send might be expensive to prepare. + +This API is optional but helpful when trying to publish messages from very +performance-senstive code. + +```js +const diagnostics_channel = require('diagnostics_channel'); + +if (diagnostics_channel.hasSubscribers('my-channel')) { + // There are subscribers, prepare and publish message +} +``` + +#### `diagnostics_channel.channel(name)` + +* `name` {string|symbol} The channel name +* Returns: {Channel} The named channel object + +This is the primary entry-point for anyone wanting to interact with a named +channel. It produces a channel object which is optimized to reduce overhead at +publish time as much as possible. + +```js +const diagnostics_channel = require('diagnostics_channel'); + +const channel = diagnostics_channel.channel('my-channel'); +``` + +### Class: `Channel` + +The class `Channel` represents an individual named channel within the data +pipeline. It is use to track subscribers and to publish messages when there +are subscribers present. It exists as a separate object to avoid channel +lookups at publish time, enabling very fast publish speeds and allowing +for heavy use while incurring very minimal cost. Channels are created with +[`diagnostics_channel.channel(name)`][], constructing a channel directly +with `new Channel(name)` is not supported. + +#### `channel.hasSubscribers` + +* Returns: {boolean} If there are active subscribers + +Check if there are active subscribers to this channel. This is helpful if +the message you want to send might be expensive to prepare. + +This API is optional but helpful when trying to publish messages from very +performance-senstive code. + +```js +const diagnostics_channel = require('diagnostics_channel'); + +const channel = diagnostics_channel.channel('my-channel'); + +if (channel.hasSubscribers) { + // There are subscribers, prepare and publish message +} +``` + +#### `channel.publish(message)` + +* `message` {any} The message to send to the channel subscribers + +Publish a message to any subscribers to the channel. This will trigger +message handlers synchronously so they will execute within the same context. + +```js +const diagnostics_channel = require('diagnostics_channel'); + +const channel = diagnostics_channel.channel('my-channel'); + +channel.publish({ + some: 'message' +}); +``` + +#### `channel.subscribe(onMessage)` + +* `onMessage` {Function} The handler to receive channel messages + * `message` {any} The message data + * `name` {string|symbol} The name of the channel + +Register a message handler to subscribe to this channel. This message handler +will be run synchronously whenever a message is published to the channel. Any +errors thrown in the message handler will trigger an [`'uncaughtException'`][]. + +```js +const diagnostics_channel = require('diagnostics_channel'); + +const channel = diagnostics_channel.channel('my-channel'); + +channel.subscribe((message, name) => { + // Received data +}); +``` + +#### `channel.unsubscribe(onMessage)` + +* `onMessage` {Function} The previous subscribed handler to remove + +Remove a message handler previously registered to this channel with +[`channel.subscribe(onMessage)`][]. + +```js +const diagnostics_channel = require('diagnostics_channel'); + +const channel = diagnostics_channel.channel('my-channel'); + +function onMessage(message, name) { + // Received data +} + +channel.subscribe(onMessage); + +channel.unsubscribe(onMessage); +``` + +[`diagnostics_channel.channel(name)`]: #diagnostics_channel_diagnostics_channel_channel_name +[`channel.subscribe(onMessage)`]: #diagnostics_channel_channel_subscribe_onmessage +[`'uncaughtException'`]: process.md#process_event_uncaughtexception |