Node.js v11.14.0 文档


timer(定时器)#

查看v10.x中文文档

Stability: 2 - Stable

The timer module exposes a global API for scheduling functions to be called at some future period of time. Because the timer functions are globals, there is no need to call require('timers') to use the API.

The timer functions within Node.js implement a similar API as the timers API provided by Web Browsers but use a different internal implementation that is built around the Node.js Event Loop.

Immediate 类#

中英对照提交修改

此对象在内部创建,并从 setImmediate() 返回。 它可以传给 clearImmediate() 以取消计划的操作。

默认情况下,当预定 immediate 时,只要 immediate 激活,Node.js 事件循环将继续运行。 setImmediate() 返回的 Immediate 对象导出 immediate.ref()immediate.unref() 函数,这些函数可用于控制此默认行为。

immediate.hasRef()#

暂无中英对照

If true, the Immediate object will keep the Node.js event loop active.

immediate.ref()#

中英对照提交修改

调用时,只要 Immediate 处于活动状态,就会请求 Node.js 事件循环不会退出。 多次调用 immediate.ref() 将无效。

默认情况下,所有 Immediate 对象都是 ref 的,通常不需要调用 immediate.ref(),除非之前调用了 immediate.unref()

immediate.unref()#

中英对照提交修改

调用时,活动的 Immediate 对象不需要 Node.js 事件循环保持活动状态。 如果没有其他活动保持事件循环运行,则进程可以在调用 Immediate 对象的回调之前退出。 多次调用 immediate.unref() 将无效。

Timeout 类#

中英对照提交修改

此对象在内部创建,并从 setTimeout()setInterval() 返回。 它可以传给 clearTimeout()clearInterval() 以取消计划的操作。

默认情况下,当使用 setTimeout()setInterval() 预定定时器时,只要定时器处于活动状态,Node.js 事件循环将继续运行。 这些函数返回的每个 Timeout 对象都会导出 timeout.ref()timeout.unref() 函数,这些函数可用于控制此默认行为。

timeout.hasRef()#

暂无中英对照

If true, the Timeout object will keep the Node.js event loop active.

timeout.ref()#

中英对照提交修改

调用时,只要 Timeout 处于活动状态,就会请求 Node.js 事件循环不会退出。 多次调用 timeout.ref() 将无效。

默认情况下,所有 Timeout 对象都是 ref 的,通常不需要调用 timeout.ref(),除非之前调用了 timeout.unref()

timeout.refresh()#

中英对照提交修改

将定时器的开始时间设置为当前时间,并重新安排定时器以在之前指定的持续时间内调用其回调,并将其调整为当前时间。 这对于在不分配新 JavaScript 对象的情况下刷新定时器非常有用。

在已调用其回调的定时器上使用此选项将重新激活定时器。

timeout.unref()#

中英对照提交修改

调用时,活动的 Timeout 对象不需要 Node.js 事件循环保持活动状态。 如果没有其他活动保持事件循环运行,则进程可以在调用 Timeout 对象的回调之前退出。 多次调用 timeout.unref() 将无效。

调用 timeout.unref() 会创建一个内部定时器,它将唤醒 Node.js 事件循环。 创建太多这些定时器可能会对 Node.js 应用程序的性能产生负面影响。

预定定时器#

中英对照提交修改

Node.js 中的定时器是一种会在一段时间后调用给定的函数的内部构造。 何时调用定时器函数取决于用来创建定时器的方法以及 Node.js 事件循环正在执行的其他工作。

setImmediate(callback[, ...args])#

中英对照提交修改

  • callback <Function> 在当前回合的 [Node.js 事件循环][the node.js event loop]结束时调用的函数。
  • ...args <any> 当调用 callback 时传入的可选参数。
  • 返回: <Immediate> 用于 clearImmediate()

预定在 I/O 事件的回调之后立即执行的 callback

当多次调用 setImmediate() 时, callback 函数将按照创建它们的顺序排队等待执行。 每次事件循环迭代都会处理整个回调队列。 如果立即定时器是从正在执行的回调排入队列,则直到下一次事件循环迭代才会触发。

如果 callback 不是函数,则抛出 TypeError

此方法具有使用 util.promisify() 的用于 Promise 的自定义变体:

const util = require('util');
const setImmediatePromise = util.promisify(setImmediate);

setImmediatePromise('foobar').then((value) => {
  // value === 'foobar' (传值是可选的)
  // 在所有 I/O 回调之后执行。
});

// 或使用异步功能。
async function timerExample() {
  console.log('在 I/O 回调之前');
  await setImmediatePromise();
  console.log('在 I/O 回调之后');
}
timerExample();

setInterval(callback, delay[, ...args])#

查看v10.x中文文档

  • callback <Function> The function to call when the timer elapses.
  • delay <number> The number of milliseconds to wait before calling the callback.
  • ...args <any> Optional arguments to pass when the callback is called.
  • Returns: <Timeout> for use with clearInterval()

Schedules repeated execution of callback every delay milliseconds.

When delay is larger than 2147483647 or less than 1, the delay will be set to 1. Non-integer delays are truncated to an integer.

If callback is not a function, a TypeError will be thrown.

setTimeout(callback, delay[, ...args])#

查看v10.x中文文档

  • callback <Function> The function to call when the timer elapses.
  • delay <number> The number of milliseconds to wait before calling the callback.
  • ...args <any> Optional arguments to pass when the callback is called.
  • Returns: <Timeout> for use with clearTimeout()

Schedules execution of a one-time callback after delay milliseconds.

The callback will likely not be invoked in precisely delay milliseconds. Node.js makes no guarantees about the exact timing of when callbacks will fire, nor of their ordering. The callback will be called as close as possible to the time specified.

When delay is larger than 2147483647 or less than 1, the delay will be set to 1. Non-integer delays are truncated to an integer.

If callback is not a function, a TypeError will be thrown.

This method has a custom variant for promises that is available using util.promisify():

const util = require('util');
const setTimeoutPromise = util.promisify(setTimeout);

setTimeoutPromise(40, 'foobar').then((value) => {
  // value === 'foobar' (passing values is optional)
  // This is executed after about 40 milliseconds.
});

取消定时器#

中英对照提交修改

setImmediate()setInterval()setTimeout() 方法各自返回表示预定的定时器的对象。 它们可用于取消定时器并防止其触发。

无法取消使用 setImmediate()setTimeout() 的 Promise 化的变体创建的定时器。

clearImmediate(immediate)#

中英对照提交修改

取消由 setImmediate() 创建的 Immediate 对象。

clearInterval(timeout)#

中英对照提交修改

取消由 setInterval() 创建的 Timeout 对象。

clearTimeout(timeout)#

查看v10.x中文文档

Cancels a Timeout object created by setTimeout().