Node.js v16.20.2 文档

公共接口#>

【Public API】

概述#>

【Overview】

以下是公共 API 的简单概述。

【Following is a simple overview of the public API.】

import diagnostics_channel from 'node:diagnostics_channel';

// Get a reusable channel object
const channel = diagnostics_channel.channel('my-channel');

function onMessage(message, name) {
  // Received data
}

// Subscribe to the channel
diagnostics_channel.subscribe('my-channel', onMessage);

// Check if the channel has an active subscriber
if (channel.hasSubscribers) {
  // Publish data to the channel
  channel.publish({
    some: 'data'
  });
}

// Unsubscribe from the channel
diagnostics_channel.unsubscribe('my-channel', onMessage);const diagnostics_channel = require('node:diagnostics_channel');

// Get a reusable channel object
const channel = diagnostics_channel.channel('my-channel');

function onMessage(message, name) {
  // Received data
}

// Subscribe to the channel
diagnostics_channel.subscribe('my-channel', onMessage);

// Check if the channel has an active subscriber
if (channel.hasSubscribers) {
  // Publish data to the channel
  channel.publish({
    some: 'data'
  });
}

// Unsubscribe from the channel
diagnostics_channel.unsubscribe('my-channel', onMessage);拷贝

diagnostics_channel.hasSubscribers(name)#>

• name <string> | <symbol> 通道名称
• 返回：<boolean> 如果有活跃的订阅者

检查指定通道是否有活跃订阅者。如果你要发送的消息准备起来可能很昂贵，这会很有用。

【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.】

此 API 是可选的，但在从对性能极其敏感的代码发布消息时非常有用。

【This API is optional but helpful when trying to publish messages from very performance-sensitive code.】

import diagnostics_channel from 'node:diagnostics_channel';

if (diagnostics_channel.hasSubscribers('my-channel')) {
  // There are subscribers, prepare and publish message
}const diagnostics_channel = require('node:diagnostics_channel');

if (diagnostics_channel.hasSubscribers('my-channel')) {
  // There are subscribers, prepare and publish message
}拷贝

diagnostics_channel.channel(name)#>

• name <string> | <symbol> 通道名称
• 返回：<Channel> 指定的通道对象

这是任何想要发布到指定通道的人的主要入口点。它生成一个通道对象，该对象经过优化，以尽可能减少发布时的开销。

【This is the primary entry-point for anyone wanting to publish to a named channel. It produces a channel object which is optimized to reduce overhead at publish time as much as possible.】

import diagnostics_channel from 'node:diagnostics_channel';

const channel = diagnostics_channel.channel('my-channel');const diagnostics_channel = require('node:diagnostics_channel');

const channel = diagnostics_channel.channel('my-channel');拷贝

diagnostics_channel.subscribe(name, onMessage)#>

• name <string> | <symbol> 通道名称
• onMessage <Function> 接收通道消息的处理程序
  • message <any> 消息数据
  • name <string> | <symbol> 通道的名称

注册一个消息处理程序以订阅此通道。每当有消息发布到该通道时，这个消息处理程序将同步执行。消息处理程序中抛出的任何错误都会触发 'uncaughtException'。

【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'.】

import diagnostics_channel from 'diagnostics_channel';

diagnostics_channel.subscribe('my-channel', (message, name) => {
  // Received data
});const diagnostics_channel = require('diagnostics_channel');

diagnostics_channel.subscribe('my-channel', (message, name) => {
  // Received data
});拷贝

diagnostics_channel.unsubscribe(name, onMessage)#>

• name <string> | <symbol> 通道名称
• onMessage <Function> 要移除的先前订阅的处理程序
• 返回：<boolean> 如果找到处理程序，则为 true，否则为 false。

移除之前使用 diagnostics_channel.subscribe(name, onMessage) 在此通道注册的消息处理程序。

【Remove a message handler previously registered to this channel with diagnostics_channel.subscribe(name, onMessage).】

import diagnostics_channel from 'diagnostics_channel';

function onMessage(message, name) {
  // Received data
}

diagnostics_channel.subscribe('my-channel', onMessage);

diagnostics_channel.unsubscribe('my-channel', onMessage);const diagnostics_channel = require('diagnostics_channel');

function onMessage(message, name) {
  // Received data
}

diagnostics_channel.subscribe('my-channel', onMessage);

diagnostics_channel.unsubscribe('my-channel', onMessage);拷贝

类：Channel#>

【Class: Channel】

类 Channel 表示数据管道中的一个名为通道的个体。它用于跟踪订阅者，并在有订阅者存在时发布消息。它作为一个独立的对象存在，以避免在发布时进行通道查找，从而实现非常快速的发布速度，并在高频使用时产生极低的成本。通道通过 diagnostics_channel.channel(name) 创建，不支持直接使用 new Channel(name) 构造通道。

【The class Channel represents an individual named channel within the data pipeline. It is used 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#>

• 返回：<boolean> 如果有活跃的订阅者

检查此通道是否有活跃的订阅者。如果你要发送的消息准备起来可能很昂贵，这会很有用。

【Check if there are active subscribers to this channel. This is helpful if the message you want to send might be expensive to prepare.】

此 API 是可选的，但在从对性能极其敏感的代码发布消息时非常有用。

【This API is optional but helpful when trying to publish messages from very performance-sensitive code.】

import diagnostics_channel from 'node:diagnostics_channel';

const channel = diagnostics_channel.channel('my-channel');

if (channel.hasSubscribers) {
  // There are subscribers, prepare and publish message
}const diagnostics_channel = require('node:diagnostics_channel');

const channel = diagnostics_channel.channel('my-channel');

if (channel.hasSubscribers) {
  // There are subscribers, prepare and publish message
}拷贝

channel.publish(message)#>

• message <any> 要发送给通道订阅者的消息

向通道的任何订阅者发布消息。这将同步触发消息处理程序，使它们在相同的上下文中执行。

【Publish a message to any subscribers to the channel. This will trigger message handlers synchronously so they will execute within the same context.】

import diagnostics_channel from 'node:diagnostics_channel';

const channel = diagnostics_channel.channel('my-channel');

channel.publish({
  some: 'message'
});const diagnostics_channel = require('node:diagnostics_channel');

const channel = diagnostics_channel.channel('my-channel');

channel.publish({
  some: 'message'
});拷贝

channel.subscribe(onMessage)#>

• onMessage <Function> 接收通道消息的处理程序
  • message <any> 消息数据
  • name <string> | <symbol> 通道的名称

注册一个消息处理程序以订阅此通道。每当有消息发布到该通道时，这个消息处理程序将同步执行。消息处理程序中抛出的任何错误都会触发 'uncaughtException'。

【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'.】

import diagnostics_channel from 'node:diagnostics_channel';

const channel = diagnostics_channel.channel('my-channel');

channel.subscribe((message, name) => {
  // Received data
});const diagnostics_channel = require('node:diagnostics_channel');

const channel = diagnostics_channel.channel('my-channel');

channel.subscribe((message, name) => {
  // Received data
});拷贝

channel.unsubscribe(onMessage)#>

• onMessage <Function> 要移除的先前订阅的处理程序
• 返回：<boolean> 如果找到处理程序，则为 true，否则为 false。

移除之前使用 channel.subscribe(onMessage) 在此通道注册的消息处理程序。

【Remove a message handler previously registered to this channel with channel.subscribe(onMessage).】

import diagnostics_channel from 'node:diagnostics_channel';

const channel = diagnostics_channel.channel('my-channel');

function onMessage(message, name) {
  // Received data
}

channel.subscribe(onMessage);

channel.unsubscribe(onMessage);const diagnostics_channel = require('node:diagnostics_channel');

const channel = diagnostics_channel.channel('my-channel');

function onMessage(message, name) {
  // Received data
}

channel.subscribe(onMessage);

channel.unsubscribe(onMessage);拷贝

内置通道#>

【Built-in Channels】

超文本传输协议#>

【HTTP】

http.client.request.start

• request <http.ClientRequest>

当客户端开始请求时触发。

【Emitted when client starts a request.】

http.client.response.finish

• request <http.ClientRequest>
• response <http.IncomingMessage>

当客户端收到响应时触发。

【Emitted when client receives a response.】

http.server.request.start

• request <http.IncomingMessage>
• response <http.ServerResponse>
• socket <net.Socket>
• server <http.Server>

当服务器收到请求时触发。

【Emitted when server receives a request.】

http.server.response.finish

• request <http.IncomingMessage>
• response <http.ServerResponse>
• socket <net.Socket>
• server <http.Server>

服务器发送响应时触发。

【Emitted when server sends a response.】

净值#>

【NET】

net.client.socket

• socket <net.Socket>

创建新的 TCP 或管道客户端套接字时触发。

【Emitted when a new TCP or pipe client socket is created.】

net.server.socket

• socket <net.Socket>

当接收到新的 TCP 或管道连接时触发。

【Emitted when a new TCP or pipe connection is received.】

用户数据报协议#>

【UDP】

udp.socket

• socket <dgram.Socket>

创建新的 UDP 套接字时触发。

【Emitted when a new UDP socket is created.】

进程#>

【Process】

child_process

• process <ChildProcess>

创建新进程时触发。

【Emitted when a new process is created.】

工作线程#>

【Worker Thread】

worker_threads

• worker Worker

创建新线程时触发。

【Emitted when a new thread is created.】