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> 通道名称

  ¥name <string> | <symbol> The channel name

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

  ¥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.

此 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> 通道名称

  ¥name <string> | <symbol> The channel name

• 返回：<Channel> 命名通道对象

  ¥Returns: <Channel> The named channel object

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

¥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> 通道名称

  ¥name <string> | <symbol> The channel name

• onMessage <Function> 接收通道消息的处理程序

  ¥onMessage <Function> The handler to receive channel messages

  • message <any> 消息数据

    ¥message <any> The message data

  • name <string> | <symbol> 通道名称

    ¥name <string> | <symbol> The name of the channel

注册消息处理程序以订阅此通道。每当消息发布到通道时，此消息处理程序将同步运行。消息处理程序中抛出的任何错误都将触发 '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> 通道名称

  ¥name <string> | <symbol> The channel name

• onMessage <Function> 要删除的先前订阅的处理程序

  ¥onMessage <Function> The previous subscribed handler to remove

• 返回：<boolean> 如果找到处理程序则为 true，否则为 false。

  ¥Returns: <boolean> true if the handler was found, false otherwise.

删除以前使用 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> 如果有活跃订阅者

  ¥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.

此 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> 要发送给通道订阅者的消息

  ¥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.

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> 接收通道消息的处理程序

  ¥onMessage <Function> The handler to receive channel messages

  • message <any> 消息数据

    ¥message <any> The message data

  • name <string> | <symbol> 通道名称

    ¥name <string> | <symbol> The name of the channel

注册消息处理程序以订阅此通道。每当消息发布到通道时，此消息处理程序将同步运行。消息处理程序中抛出的任何错误都将触发 '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> 要删除的先前订阅的处理程序

  ¥onMessage <Function> The previous subscribed handler to remove

• 返回：<boolean> 如果找到处理程序则为 true，否则为 false。

  ¥Returns: <boolean> true if the handler was found, false otherwise.

删除以前使用 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.