目录

• timer（定时器）

  • Immediate 类

    • immediate.hasRef()
    • immediate.ref()
    • immediate.unref()

  • Timeout 类

    • timeout.hasRef()
    • timeout.ref()
    • timeout.refresh()
    • timeout.unref()
    • timeout[Symbol.toPrimitive]()

  • 安排定时器

    • setImmediate(callback[, ...args])
    • setInterval(callback, delay[, ...args])
    • setTimeout(callback, delay[, ...args])

  • 取消定时器

    • clearImmediate(immediate)
    • clearInterval(timeout)
    • clearTimeout(timeout)

timer（定时器）#

中英对照提交修改

源代码: lib/timers.js

timer 模块开放了一个全局的 API，用于安排函数在未来某个时间点被调用。 因为定时器函数是全局的，所以使用 API 不需要调用 require('timers')。

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

Immediate 类#

中英对照提交修改

此对象在 setImmediate() 内部创建并返回。 它可以传给 clearImmediate() 以取消已安排的行动。

默认情况下，当一个 immediate 被安排时，只要 immediate 处于活动状态，则 Node.js 事件循环就会继续运行。 setImmediate() 返回的 Immediate 对象会导出 immediate.ref() 和 immediate.unref() 函数，可用于控制此默认的行为。

immediate.hasRef()#

中英对照提交修改

• 返回: <boolean>

如果为 true，则 Immediate 对象将会使 Node.js 事件循环保持活动状态。

immediate.ref()#

中英对照提交修改

• 返回: <Immediate> immediate 的引用。

当被调用时，则只要 Immediate 处于活动状态，就会要求 Node.js 事件循环不要退出。 多次调用 immediate.ref() 没有影响。

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

immediate.unref()#

中英对照提交修改

• 返回: <Immediate> immediate 的引用。

当被调用时，活动的 Immediate 对象将不会要求 Node.js 事件循环保持活动状态。 如果没有其他的活动保持事件循环运行，则进程可能会在 Immediate 对象的回调被调用之前退出。 多次调用 immediate.unref() 没有影响。

Timeout 类#

中英对照提交修改

此对象在 setTimeout() 和 setInterval() 内部创建并返回。 它可以传给 clearTimeout() 或 clearInterval() 以取消已安排的行动。

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

timeout.hasRef()#

中英对照提交修改

• 返回: <boolean>

如果为 true，则 Timeout 对象将会使 Node.js 事件循环保持活动状态。

timeout.ref()#

中英对照提交修改

• 返回: <Timeout> timeout 的引用。

当被调用时，则只要 Timeout 处于活动状态，就会要求 Node.js 事件循环不要退出。 多次调用 timeout.ref() 没有影响。

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

timeout.refresh()#

中英对照提交修改

• 返回: <Timeout> timeout 的引用。

将定时器的开始时间设置为当前时间，并重新安排定时器以便按之前指定的时长（以当前时间进行调整）调用其回调。 这对于在不分配新的 JavaScript 对象的情况下刷新定时器非常有用。

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

timeout.unref()#

中英对照提交修改

• 返回: <Timeout> timeout 的引用。

当被调用时，活动的 Timeout 对象将不会要求 Node.js 事件循环保持活动状态。 如果没有其他的活动保持事件循环运行，则进程可能会在 Timeout 对象的回调被调用之前退出。 多次调用 timeout.unref() 没有影响。

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

timeout[Symbol.toPrimitive]()#

暂无中英对照提交修改

• Returns: <integer> number that can be used to reference this timeout

Coerce a Timeout to a primitive, a primitive will be generated that can be used to clear the Timeout. The generated number can only be used in the same thread where timeout was created. Therefore to use it cross worker_threads it has to first be passed to a correct thread. This allows enhanced compatibility with browser's setTimeout(), and setInterval() implementations.

安排定时器#

中英对照提交修改

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

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

中英对照提交修改

• callback <Function> Node.js 事件循环的此回合结束时要调用的函数。
• ...args <any> 当调用 callback 时传入的可选的参数。
• 返回: <Immediate> 用于 clearImmediate()。

安排在 I/O 事件的回调之后立即执行的 callback。

当多次调用 setImmediate() 时， callback 函数会按它们被创建的顺序放入排队等待执行。 每轮的事件循环迭代都会处理整个回调队列。 如果一个 immediate 定时器是从一个正在执行中的回调内部被放入队列，则该定时器将不会被触发，直到下一轮的事件循环迭代。

如果 callback 不是函数，则抛出 TypeError。

此方法有一个定制的用于 promise 的变体，使用 util.promisify() 创建：

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

中英对照提交修改

• callback <Function> 当定时器到点时调用的函数。
• delay <number> 调用 callback 之前等待的毫秒数。
• ...args <any> 当调用 callback 时传入的可选参数。
• 返回: <Timeout> 用于 clearInterval()。

安排每隔 delay 毫秒重复执行 callback。

当 delay 大于 2147483647 或小于 1 时，则 delay 将会被设置为 1。 非整数的 delay 会被截断为整数。

如果 callback 不是函数，则抛出 TypeError。

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

中英对照提交修改

• callback <Function> 当定时器到点时调用的函数。
• delay <number> 调用 callback 之前等待的毫秒数。
• ...args <any> 当调用 callback 时传入的可选参数。
• 返回: <Timeout> 用于 clearTimeout()。

安排在 delay 毫秒之后执行一次性的 callback。

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

当 delay 大于 2147483647 或小于 1 时，则 delay 将会被设置为 1。 非整数的 delay 会被截断为整数。

如果 callback 不是函数，则抛出 TypeError。

此方法有一个定制的用于 promise 的变体，使用 util.promisify() 创建：

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

中英对照提交修改

• immediate <Immediate> setImmediate() 返回的 Immediate 对象。

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

clearInterval(timeout)#

中英对照提交修改

• timeout <Timeout> setInterval() 返回的 Timeout 对象。

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

clearTimeout(timeout)#

中英对照提交修改

• timeout <Timeout> setTimeout() 返回的 Timeout 对象。

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