Node.js v10.15.3 文档


timer(定时器)#

中英对照提交修改

稳定性: 2 - 稳定

timer 模块暴露了一个全局的 API,用于预定在将来某个时间段调用的函数。 因为定时器函数是全局变量,所以不需要调用 require('timers') 来使用 API。

Node.js 中的定时器函数实现了与 Web 浏览器提供的定时器 API 类似的 API,但是使用了不同的内部实现(基于 Node.js 事件循环构建)。

Immediate 类#

中英对照提交修改

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

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

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.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])#

中英对照提交修改

预定在 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])#

中英对照提交修改

预定每隔 delay 毫秒重复执行 callback

delay 大于 2147483647 或小于 1 时, delay 将设置为 1

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

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

中英对照提交修改

预定在 delay 毫秒之后执行一次性的 callback

可能不会精确地在 delay 毫秒时调用 callback。 Node.js 不保证回调被触发的确切时间,也不保证它们的顺序。 回调会在尽可能接近指定的时间调用。

delay 大于 2147483647 或小于 1 时, delay 将设置为 1

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

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

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

setTimeoutPromise(40, 'foobar').then((value) => {
  // value === 'foobar' (传值是可选的)
  // 在大约 40 毫秒后执行。
});

取消定时器#

中英对照提交修改

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

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

clearImmediate(immediate)#

中英对照提交修改

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

clearInterval(timeout)#

中英对照提交修改

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

clearTimeout(timeout)#

中英对照提交修改

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