目录

• 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> a number that can be used to reference this timeout

Coerce a Timeout to a primitive. The primitive can be used to clear the Timeout. The primitive can only be used in the same thread where the timeout was created. Therefore, to use it across worker_threads it must first be passed to the correct thread. This allows enhanced compatibility with browser 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 对象。