타이머

[안정성: 2 - 안정됨]

timer 모듈은 미래의 특정 시점에 호출될 함수를 예약하기 위한 전역 API를 제공합니다. 타이머 함수는 전역이므로 API를 사용하기 위해 require('node:timers')를 호출할 필요가 없습니다.

Node.js 내부의 타이머 함수는 웹 브라우저에서 제공하는 타이머 API와 유사한 API를 구현하지만, Node.js 이벤트 루프를 중심으로 구축된 다른 내부 구현을 사용합니다.

클래스: `Immediate`

이 객체는 내부적으로 생성되며 setImmediate()에서 반환됩니다. 예약된 작업을 취소하기 위해 clearImmediate()에 전달할 수 있습니다.

기본적으로 immediate가 예약되면 Node.js 이벤트 루프는 immediate가 활성 상태인 동안 계속 실행됩니다. setImmediate()에서 반환된 Immediate 객체는 이러한 기본 동작을 제어하는 데 사용할 수 있는 immediate.ref() 및 immediate.unref() 함수를 모두 내보냅니다.

`immediate.hasRef()`

추가된 버전: v11.0.0

반환값: <boolean>

true이면 Immediate 객체가 Node.js 이벤트 루프를 활성 상태로 유지합니다.

`immediate.ref()`

추가된 버전: v9.7.0

반환값: <Immediate> immediate에 대한 참조

호출되면 Immediate가 활성 상태인 한 Node.js 이벤트 루프가 종료되지 않도록 요청합니다. immediate.ref()를 여러 번 호출해도 아무런 효과가 없습니다.

기본적으로 모든 Immediate 객체는 "ref'ed" 상태이므로, 이전에 immediate.unref()가 호출되지 않은 경우 일반적으로 immediate.ref()를 호출할 필요가 없습니다.

`immediate.unref()`

추가된 버전: v9.7.0

반환 값: <Immediate> immediate에 대한 참조

호출되면 활성 Immediate 객체는 Node.js 이벤트 루프가 활성 상태를 유지하는 데 필요하지 않습니다. 이벤트 루프를 실행 상태로 유지하는 다른 활동이 없으면 Immediate 객체의 콜백이 호출되기 전에 프로세스가 종료될 수 있습니다. immediate.unref()를 여러 번 호출해도 아무런 효과가 없습니다.

`immediate[Symbol.dispose]()`

추가된 버전: v20.5.0, v18.18.0

[안정성: 1 - 실험적]

안정성: 1 안정성: 1 - 실험적

immediate를 취소합니다. 이는 clearImmediate()를 호출하는 것과 유사합니다.

클래스: `Timeout`

이 객체는 내부적으로 생성되며 setTimeout() 및 setInterval()에서 반환됩니다. 예약된 작업을 취소하기 위해 clearTimeout() 또는 clearInterval()에 전달될 수 있습니다.

기본적으로 setTimeout() 또는 setInterval() 중 하나를 사용하여 타이머를 예약하면 타이머가 활성 상태인 동안 Node.js 이벤트 루프는 계속 실행됩니다. 이러한 함수에서 반환된 각 Timeout 객체는 이 기본 동작을 제어하는 데 사용할 수 있는 timeout.ref() 및 timeout.unref() 함수를 모두 내보냅니다.

`timeout.close()`

추가된 버전: v0.9.1

[안정성: 3 - 레거시]

안정성: 3 안정성: 3 - 레거시: 대신 clearTimeout()를 사용하세요.

반환 값: <Timeout> timeout에 대한 참조

타임아웃을 취소합니다.

`timeout.hasRef()`

추가된 버전: v11.0.0

반환 값: <boolean>

true이면 Timeout 객체가 Node.js 이벤트 루프를 활성 상태로 유지합니다.

`timeout.ref()`

추가된 버전: v0.9.1

반환값: <Timeout> timeout에 대한 참조

호출되면 Node.js 이벤트 루프가 Timeout이 활성 상태인 동안에는 종료되지 않도록 요청합니다. timeout.ref()를 여러 번 호출해도 아무런 효과가 없습니다.

기본적으로 모든 Timeout 객체는 "ref'ed"로 설정되어 있으므로 일반적으로 timeout.unref()가 이전에 호출되지 않은 경우 timeout.ref()를 호출할 필요가 없습니다.

`timeout.refresh()`

추가된 버전: v10.2.0

반환값: <Timeout> timeout에 대한 참조

타이머의 시작 시간을 현재 시간으로 설정하고 타이머가 현재 시간에 맞춰 조정된 이전에 지정된 기간에 콜백을 호출하도록 다시 예약합니다. 이는 새로운 JavaScript 객체를 할당하지 않고 타이머를 새로 고치는 데 유용합니다.

콜백을 이미 호출한 타이머에서 이를 사용하면 타이머가 다시 활성화됩니다.

`timeout.unref()`

추가된 버전: v0.9.1

반환값: <Timeout> timeout에 대한 참조

호출되면 활성 Timeout 객체가 Node.js 이벤트 루프가 활성 상태를 유지하는 데 필요하지 않습니다. 이벤트 루프를 계속 실행하는 다른 활동이 없으면 Timeout 객체의 콜백이 호출되기 전에 프로세스가 종료될 수 있습니다. timeout.unref()를 여러 번 호출해도 아무런 효과가 없습니다.

`timeout[Symbol.toPrimitive]()`

추가된 버전: v14.9.0, v12.19.0

반환값: <integer> 이 timeout을 참조하는 데 사용할 수 있는 숫자

Timeout을 기본형으로 강제 변환합니다. 기본형은 Timeout을 지우는 데 사용할 수 있습니다. 기본형은 타임아웃이 생성된 동일한 스레드에서만 사용할 수 있습니다. 따라서 worker_threads에서 사용하려면 먼저 올바른 스레드로 전달해야 합니다. 이를 통해 브라우저 setTimeout() 및 setInterval() 구현과의 호환성이 향상됩니다.

`timeout[Symbol.dispose]()`

추가된 버전: v20.5.0, v18.18.0

[안정화: 1 - 실험적]

안정화: 1 안정화: 1 - 실험적

타임아웃을 취소합니다.

타이머 스케줄링

Node.js에서 타이머는 특정 시간 간격 후 주어진 함수를 호출하는 내부 구조입니다. 타이머의 함수가 호출되는 시점은 타이머를 생성하는 데 사용된 메서드와 Node.js 이벤트 루프가 수행하는 다른 작업에 따라 달라집니다.

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

[기록]

버전	변경 사항
v18.0.0	`callback` 인수에 유효하지 않은 콜백을 전달하면 `ERR_INVALID_CALLBACK` 대신 `ERR_INVALID_ARG_TYPE`을 throw합니다.
v0.9.1	추가됨: v0.9.1

callback <Function> Node.js 이벤트 루프의 이번 턴이 끝날 때 호출할 함수
...args <any> callback이 호출될 때 전달할 선택적 인수입니다.
반환: clearImmediate()와 함께 사용할 <Immediate>

I/O 이벤트 콜백 이후에 callback의 "즉시" 실행을 예약합니다.

setImmediate()를 여러 번 호출하면 callback 함수는 생성된 순서대로 실행 대기열에 추가됩니다. 전체 콜백 대기열은 모든 이벤트 루프 반복마다 처리됩니다. 실행 중인 콜백 내부에서 즉시 타이머가 대기열에 추가되면 해당 타이머는 다음 이벤트 루프 반복까지 트리거되지 않습니다.

callback이 함수가 아니면 TypeError가 throw됩니다.

이 메서드에는 timersPromises.setImmediate()를 사용하여 사용할 수 있는 사용자 지정 Promise 변형이 있습니다.

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

[기록]

버전	변경 사항
v18.0.0	`callback` 인수에 유효하지 않은 콜백을 전달하면 `ERR_INVALID_CALLBACK` 대신 `ERR_INVALID_ARG_TYPE`을 throw합니다.
v0.0.1	추가됨: v0.0.1

callback <Function> 타이머가 경과할 때 호출할 함수
delay <number> callback을 호출하기 전에 기다릴 밀리초 수. 기본값: 1.
...args <any> callback이 호출될 때 전달할 선택적 인수입니다.
반환: clearInterval()와 함께 사용할 <Timeout>

delay 밀리초마다 callback의 반복 실행을 예약합니다.

delay가 2147483647보다 크거나 1보다 작거나 NaN이면 delay가 1로 설정됩니다. 정수가 아닌 지연은 정수로 잘립니다.

callback이 함수가 아니면 TypeError가 throw됩니다.

이 메서드에는 timersPromises.setInterval()를 사용하여 사용할 수 있는 사용자 지정 Promise 변형이 있습니다.

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

[History]

Version	Changes
v18.0.0	`callback` 인수에 유효하지 않은 콜백을 전달하면 이제 `ERR_INVALID_CALLBACK` 대신 `ERR_INVALID_ARG_TYPE`이 발생합니다.
v0.0.1	Added in: v0.0.1

callback <Function> 타이머가 만료될 때 호출할 함수입니다.
delay <number> callback을 호출하기 전에 대기할 밀리초 수입니다. 기본값: 1.
...args <any> callback이 호출될 때 전달할 선택적 인수입니다.
반환값: clearTimeout()과 함께 사용할 <Timeout>

delay 밀리초 후에 일회성 callback 실행을 예약합니다.

callback은 정확히 delay 밀리초 내에 호출되지 않을 수 있습니다. Node.js는 콜백이 발생하는 정확한 시기나 순서에 대해 보장하지 않습니다. 콜백은 지정된 시간에 최대한 가깝게 호출됩니다.

delay가 2147483647보다 크거나 1보다 작거나 NaN이면 delay는 1로 설정됩니다. 정수가 아닌 지연은 정수로 잘립니다.

callback이 함수가 아니면 TypeError가 발생합니다.

이 메서드는 timersPromises.setTimeout()을 사용하여 사용할 수 있는 프로미스에 대한 사용자 정의 변형이 있습니다.

타이머 취소

setImmediate(), setInterval() 및 setTimeout() 메서드는 각각 예약된 타이머를 나타내는 객체를 반환합니다. 이를 사용하여 타이머를 취소하고 트리거되는 것을 방지할 수 있습니다.

setImmediate() 및 setTimeout()의 프로미스화된 변형의 경우, AbortController를 사용하여 타이머를 취소할 수 있습니다. 취소되면 반환된 Promise는 'AbortError'와 함께 거부됩니다.

setImmediate()의 경우:

ESMCJS

import { setImmediate as setImmediatePromise } from 'node:timers/promises'

const ac = new AbortController()
const signal = ac.signal

// Promise를 `await`하지 않으므로 `ac.abort()`가 동시에 호출됩니다.
setImmediatePromise('foobar', { signal })
  .then(console.log)
  .catch(err => {
    if (err.name === 'AbortError') console.error('즉시 호출이 중단되었습니다.')
  })

ac.abort()

const { setImmediate: setImmediatePromise } = require('node:timers/promises')

const ac = new AbortController()
const signal = ac.signal

setImmediatePromise('foobar', { signal })
  .then(console.log)
  .catch(err => {
    if (err.name === 'AbortError') console.error('즉시 호출이 중단되었습니다.')
  })

ac.abort()

setTimeout()의 경우:

ESMCJS

import { setTimeout as setTimeoutPromise } from 'node:timers/promises'

const ac = new AbortController()
const signal = ac.signal

// Promise를 `await`하지 않으므로 `ac.abort()`가 동시에 호출됩니다.
setTimeoutPromise(1000, 'foobar', { signal })
  .then(console.log)
  .catch(err => {
    if (err.name === 'AbortError') console.error('타임아웃이 중단되었습니다.')
  })

ac.abort()

const { setTimeout: setTimeoutPromise } = require('node:timers/promises')

const ac = new AbortController()
const signal = ac.signal

setTimeoutPromise(1000, 'foobar', { signal })
  .then(console.log)
  .catch(err => {
    if (err.name === 'AbortError') console.error('타임아웃이 중단되었습니다.')
  })

ac.abort()

`clearImmediate(immediate)`

추가된 버전: v0.9.1

immediate <Immediate> setImmediate()에 의해 반환된 Immediate 객체입니다.

setImmediate()에 의해 생성된 Immediate 객체를 취소합니다.

`clearInterval(timeout)`

추가된 버전: v0.0.1

timeout <Timeout> | <string> | <number> setInterval()에 의해 반환된 Timeout 객체이거나, 문자열 또는 숫자로 표현된 Timeout 객체의 기본형입니다.

setInterval()에 의해 생성된 Timeout 객체를 취소합니다.

`clearTimeout(timeout)`

추가된 버전: v0.0.1

timeout <Timeout> | <string> | <number> setTimeout()에 의해 반환된 Timeout 객체이거나, 문자열 또는 숫자로 표현된 Timeout 객체의 기본형입니다.

setTimeout()에 의해 생성된 Timeout 객체를 취소합니다.

타이머 Promise API

[기록]

버전	변경 사항
v16.0.0	실험적 기능에서 졸업했습니다.
v15.0.0	추가된 버전: v15.0.0

timers/promises API는 Promise 객체를 반환하는 대체 타이머 함수 세트를 제공합니다. API는 require('node:timers/promises')를 통해 접근할 수 있습니다.

ESMCJS

import { setTimeout, setImmediate, setInterval } from 'node:timers/promises'

const { setTimeout, setImmediate, setInterval } = require('node:timers/promises')

`timersPromises.setTimeout([delay[, value[, options]]])`

추가된 버전: v15.0.0

delay <number> 프로미스가 이행되기 전에 기다릴 밀리초 수입니다. 기본값: 1.
value <any> 프로미스가 이행될 값입니다.
options <Object>
- ref <boolean> 예약된 Timeout이 Node.js 이벤트 루프가 활성 상태를 유지할 필요가 없음을 나타내려면 false로 설정합니다. 기본값: true.
- signal <AbortSignal> 예약된 Timeout을 취소하는 데 사용할 수 있는 선택적 AbortSignal입니다.

ESMCJS

import { setTimeout } from 'node:timers/promises'

const res = await setTimeout(100, 'result')

console.log(res) // 'result' 출력

const { setTimeout } = require('node:timers/promises')

setTimeout(100, 'result').then(res => {
  console.log(res) // 'result' 출력
})

`timersPromises.setImmediate([value[, options]])`

추가된 버전: v15.0.0

value <any> 프로미스가 이행될 값입니다.
options <Object>
- ref <boolean> 예약된 Immediate가 Node.js 이벤트 루프가 활성 상태를 유지할 필요가 없음을 나타내려면 false로 설정합니다. 기본값: true.
- signal <AbortSignal> 예약된 Immediate를 취소하는 데 사용할 수 있는 선택적 AbortSignal입니다.

ESMCJS

import { setImmediate } from 'node:timers/promises'

const res = await setImmediate('result')

console.log(res) // 'result' 출력

const { setImmediate } = require('node:timers/promises')

setImmediate('result').then(res => {
  console.log(res) // 'result' 출력
})

`timersPromises.setInterval([delay[, value[, options]]])`

Added in: v15.9.0

delay ms 간격으로 값을 생성하는 비동기 반복자를 반환합니다. ref가 true인 경우 이벤트 루프를 활성 상태로 유지하려면 비동기 반복자의 next()를 명시적으로 또는 암시적으로 호출해야 합니다.

delay <number> 반복 간에 대기할 밀리초 수입니다. 기본값: 1.
value <any> 반복자가 반환하는 값입니다.
options <Object>
- ref <boolean> 반복 간에 예약된 Timeout이 Node.js 이벤트 루프를 활성 상태로 유지할 필요가 없음을 나타내려면 false로 설정합니다. 기본값: true.
- signal <AbortSignal> 작업 간에 예약된 Timeout을 취소하는 데 사용할 수 있는 선택적 AbortSignal입니다.

ESMCJS

import { setInterval } from 'node:timers/promises'

const interval = 100
for await (const startTime of setInterval(interval, Date.now())) {
  const now = Date.now()
  console.log(now)
  if (now - startTime > 1000) break
}
console.log(Date.now())

const { setInterval } = require('node:timers/promises')
const interval = 100

;(async function () {
  for await (const startTime of setInterval(interval, Date.now())) {
    const now = Date.now()
    console.log(now)
    if (now - startTime > 1000) break
  }
  console.log(Date.now())
})()

`timersPromises.scheduler.wait(delay[, options])`

Added in: v17.3.0, v16.14.0

[Stable: 1 - Experimental]

Stable: 1 Stability: 1 - Experimental

delay <number> Promise를 resolve하기 전에 대기할 밀리초 수입니다.
options <Object>
- ref <boolean> 예약된 Timeout이 Node.js 이벤트 루프를 활성 상태로 유지할 필요가 없음을 나타내려면 false로 설정합니다. 기본값: true.
- signal <AbortSignal> 대기를 취소하는 데 사용할 수 있는 선택적 AbortSignal입니다.
반환: <Promise>

표준 웹 플랫폼 API로 개발 중인 Scheduling APIs 초안 사양에 의해 정의된 실험적 API입니다.

timersPromises.scheduler.wait(delay, options)를 호출하는 것은 timersPromises.setTimeout(delay, undefined, options)를 호출하는 것과 같습니다.

import { scheduler } from 'node:timers/promises'

await scheduler.wait(1000) // 계속하기 전에 1초 대기

`timersPromises.scheduler.yield()`

추가된 버전: v17.3.0, v16.14.0

::: 경고 [안정성: 1 - 실험적] 안정성: 1 안정성: 1 - 실험적 :::

반환값: <Promise>

표준 웹 플랫폼 API로 개발 중인 Scheduling APIs 초안 사양에 정의된 실험적 API입니다.

timersPromises.scheduler.yield()를 호출하는 것은 인자 없이 timersPromises.setImmediate()를 호출하는 것과 같습니다.

타이머 ​

클래스: Immediate ​

immediate.hasRef() ​

immediate.ref() ​

immediate.unref() ​

immediate[Symbol.dispose]() ​

클래스: Timeout ​

timeout.close() ​

timeout.hasRef() ​

timeout.ref() ​

timeout.refresh() ​

timeout.unref() ​

timeout[Symbol.toPrimitive]() ​

timeout[Symbol.dispose]() ​

타이머 스케줄링 ​

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

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

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

타이머 취소 ​

clearImmediate(immediate) ​

clearInterval(timeout) ​

clearTimeout(timeout) ​

타이머 Promise API ​

timersPromises.setTimeout([delay[, value[, options]]]) ​

timersPromises.setImmediate([value[, options]]) ​

timersPromises.setInterval([delay[, value[, options]]]) ​

timersPromises.scheduler.wait(delay[, options]) ​

timersPromises.scheduler.yield() ​

타이머

클래스: `Immediate`

`immediate.hasRef()`

`immediate.ref()`

`immediate.unref()`

`immediate[Symbol.dispose]()`

클래스: `Timeout`

`timeout.close()`

`timeout.hasRef()`

`timeout.ref()`

`timeout.refresh()`

`timeout.unref()`

`timeout[Symbol.toPrimitive]()`

`timeout[Symbol.dispose]()`

타이머 스케줄링

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

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

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

타이머 취소

`clearImmediate(immediate)`

`clearInterval(timeout)`

`clearTimeout(timeout)`

타이머 Promise API

`timersPromises.setTimeout([delay[, value[, options]]])`

`timersPromises.setImmediate([value[, options]])`

`timersPromises.setInterval([delay[, value[, options]]])`

`timersPromises.scheduler.wait(delay[, options])`

`timersPromises.scheduler.yield()`