From 8c8c97da6109dce16a5ee444bc4b75af5298a1fa Mon Sep 17 00:00:00 2001 From: Stephen Belanger Date: Tue, 31 May 2022 10:52:09 -0700 Subject: [PATCH] doc: deprecate diagnostics_channel object subscribe method MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit PR-URL: https://github.com/nodejs/node/pull/42714 Reviewed-By: James M Snell Reviewed-By: Chengzhong Wu Reviewed-By: Gerhard Stöbich Reviewed-By: Rafael Gonzaga Reviewed-By: Vladimir de Turckheim --- doc/api/deprecations.md | 20 ++++++++++++++++++++ doc/api/diagnostics_channel.md | 9 ++++++++- 2 files changed, 28 insertions(+), 1 deletion(-) diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index 11debc3f2cd53c..987025a571e16e 100644 --- a/doc/api/deprecations.md +++ b/doc/api/deprecations.md @@ -3137,6 +3137,24 @@ parameter in [`fs.write()`][], [`fs.writeFile()`][], [`fs.appendFile()`][], [`fs.writeFileSync()`][], and [`fs.appendFileSync()`][] is deprecated. Convert them to primitive strings. +### DEP0163: `channel.subscribe(onMessage)`, `channel.unsubscribe(onMessage)` + + + +Type: Documentation-only + +These methods were deprecated because they can be used in a way which does not +hold the channel reference alive long enough to receive the events. + +Use [`diagnostics_channel.subscribe(name, onMessage)`][] or +[`diagnostics_channel.unsubscribe(name, onMessage)`][] which does the same +thing instead. + [Legacy URL API]: url.md#legacy-url-api [NIST SP 800-38D]: https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38d.pdf [RFC 6066]: https://tools.ietf.org/html/rfc6066#section-3 @@ -3177,6 +3195,8 @@ Convert them to primitive strings. [`crypto.scrypt()`]: crypto.md#cryptoscryptpassword-salt-keylen-options-callback [`decipher.final()`]: crypto.md#decipherfinaloutputencoding [`decipher.setAuthTag()`]: crypto.md#deciphersetauthtagbuffer-encoding +[`diagnostics_channel.subscribe(name, onMessage)`]: diagnostics_channel.md#diagnostics_channelsubscribename-onmessage +[`diagnostics_channel.unsubscribe(name, onMessage)`]: diagnostics_channel.md#diagnostics_channelunsubscribename-onmessage [`dns.lookup()`]: dns.md#dnslookuphostname-options-callback [`dnsPromises.lookup()`]: dns.md#dnspromiseslookuphostname-options [`domain`]: domain.md diff --git a/doc/api/diagnostics_channel.md b/doc/api/diagnostics_channel.md index 9f805c226d0d1f..04a602195848a3 100644 --- a/doc/api/diagnostics_channel.md +++ b/doc/api/diagnostics_channel.md @@ -308,8 +308,11 @@ channel.publish({ added: - v15.1.0 - v14.17.0 +deprecated: REPLACEME --> +> Stability: 0 - Deprecated: Use [`diagnostics_channel.subscribe(name, onMessage)`][] + * `onMessage` {Function} The handler to receive channel messages * `message` {any} The message data * `name` {string|symbol} The name of the channel @@ -344,6 +347,7 @@ channel.subscribe((message, name) => { added: - v15.1.0 - v14.17.0 +deprecated: REPLACEME changes: - version: - v17.1.0 @@ -353,6 +357,8 @@ changes: description: Added return value. Added to channels without subscribers. --> +> Stability: 0 - Deprecated: Use [`diagnostics_channel.unsubscribe(name, onMessage)`][] + * `onMessage` {Function} The previous subscribed handler to remove * Returns: {boolean} `true` if the handler was found, `false` otherwise. @@ -424,5 +430,6 @@ Emitted when server sends a response. [`'uncaughtException'`]: process.md#event-uncaughtexception [`channel.subscribe(onMessage)`]: #channelsubscribeonmessage -[`diagnostics_channel.subscribe(name, onMessage)`]: #diagnostics_channelunsubscribename_onmessage [`diagnostics_channel.channel(name)`]: #diagnostics_channelchannelname +[`diagnostics_channel.subscribe(name, onMessage)`]: #diagnostics_channelsubscribename-onmessage +[`diagnostics_channel.unsubscribe(name, onMessage)`]: #diagnostics_channelunsubscribename-onmessage