Node.js v12.4.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])#

查看v10.x中文文档

  • callback <Function> The function to call at the end of this turn of [the Node.js Event Loop]
  • ...args <any> Optional arguments to pass when the callback is called.
  • Returns: <Immediate> for use with clearImmediate()

Schedules the "immediate" execution of the callback after I/O events' callbacks.

When multiple calls to setImmediate() are made, the callback functions are queued for execution in the order in which they are created. The entire callback queue is processed every event loop iteration. If an immediate timer is queued from inside an executing callback, that timer will not be triggered until the next event loop iteration.

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 setImmediatePromise = util.promisify(setImmediate);

setImmediatePromise('foobar').then((value) => {
  // value === 'foobar' (passing values is optional)
  // This is executed after all I/O callbacks.
});

// Or with async function
async function timerExample() {
  console.log('Before I/O callbacks');
  await setImmediatePromise();
  console.log('After I/O callbacks');
}
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().