diff --git a/doc/api/diagnostics_channel.md b/doc/api/diagnostics_channel.md index 40d3372b5cf..036292f358c 100644 --- a/doc/api/diagnostics_channel.md +++ b/doc/api/diagnostics_channel.md @@ -165,12 +165,17 @@ const channel = diagnostics_channel.channel('my-channel'); added: - v18.7.0 - v16.17.0 +changes: + - version: REPLACEME + pr-url: https://github.com/nodejs/node/pull/65383 + description: Returns a `Disposable` which removes the handler. --> * `name` {string|symbol} The channel name * `onMessage` {Function} The handler to receive channel messages * `message` {any} The message data * `name` {string|symbol} The name of the channel +* Returns: {Disposable} A Disposable that removes the message handler. 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 @@ -192,6 +197,32 @@ diagnostics_channel.subscribe('my-channel', (message, name) => { }); ``` +The returned Disposable removes the message handler, which allows the +subscription to be scoped with the [`using`][] syntax. Disposing it more than +once has no further effect. + +```mjs +import diagnostics_channel from 'node:diagnostics_channel'; + +{ + using subscription = diagnostics_channel.subscribe('my-channel', (message, name) => { + // Received data + }); +} +// The handler is removed on scope exit +``` + +```cjs +const diagnostics_channel = require('node:diagnostics_channel'); + +{ + using subscription = diagnostics_channel.subscribe('my-channel', (message, name) => { + // Received data + }); +} +// The handler is removed on scope exit +``` + #### `diagnostics_channel.unsubscribe(name, onMessage)` * `subscribers` {Object} Set of [TracingChannel Channels][] subscribers @@ -778,6 +850,8 @@ added: * `asyncStart` {Function} The [`asyncStart` event][] subscriber * `asyncEnd` {Function} The [`asyncEnd` event][] subscriber * `error` {Function} The [`error` event][] subscriber +* Returns: {Disposable} A Disposable that removes every subscriber the call + registered. Helper to subscribe a collection of functions to the corresponding channels. This is the same as calling [`channel.subscribe(onMessage)`][] on each channel @@ -831,6 +905,46 @@ channels.subscribe({ }); ``` +The returned Disposable removes every subscriber the call registered, which +allows the whole set to be scoped with the [`using`][] syntax. Disposing it more +than once has no further effect. + +```mjs +import diagnostics_channel from 'node:diagnostics_channel'; + +const channels = diagnostics_channel.tracingChannel('my-channel'); + +{ + using subscription = channels.subscribe({ + start(message) { + // Handle start message + }, + end(message) { + // Handle end message + }, + }); +} +// Both handlers are removed on scope exit +``` + +```cjs +const diagnostics_channel = require('node:diagnostics_channel'); + +const channels = diagnostics_channel.tracingChannel('my-channel'); + +{ + using subscription = channels.subscribe({ + start(message) { + // Handle start message + }, + end(message) { + // Handle end message + }, + }); +} +// Both handlers are removed on scope exit +``` + #### `tracingChannel.unsubscribe(subscribers)` * `handlers` {Object} Set of channel subscribers * `start` {Function} The start event subscriber * `end` {Function} The end event subscriber +* Returns: {Disposable} A Disposable that removes every subscriber the call + registered. Subscribe to the bounded channel events. This is equivalent to calling [`channel.subscribe(onMessage)`][] on each channel individually. @@ -1247,6 +1367,46 @@ wc.subscribe({ }); ``` +The returned Disposable removes every subscriber the call registered, which +allows the whole set to be scoped with the [`using`][] syntax. Disposing it more +than once has no further effect. + +```mjs +import { boundedChannel } from 'node:diagnostics_channel'; + +const wc = boundedChannel('my-operation'); + +{ + using subscription = wc.subscribe({ + start(message) { + // Handle start + }, + end(message) { + // Handle end + }, + }); +} +// Both handlers are removed on scope exit +``` + +```cjs +const { boundedChannel } = require('node:diagnostics_channel'); + +const wc = boundedChannel('my-operation'); + +{ + using subscription = wc.subscribe({ + start(message) { + // Handle start + }, + end(message) { + // Handle end + }, + }); +} +// Both handlers are removed on scope exit +``` + #### `boundedChannel.unsubscribe(handlers)`