Cloudflare Docs
Durable Objects
Cloudflare Docs
Durable Objects
GitHub icon
Edit this page on GitHub
Set theme to dark (⇧+D)
  1. Products
  2. Durable Objects
  3. API
  4. Alarms

Alarms

​​ Background

Durable Objects alarms allow you to schedule the Durable Object to be woken up at a time in the future. When the alarm’s scheduled time comes, the alarm() handler method will be called.

Alarms are modified using the Transactional Storage API. Alarm operations follow the same rules as other storage operations. Each Durable Object instance is able to schedule a single alarm at a time by calling setAlarm().

Alarms have guaranteed at-least-once execution and are retried automatically when the alarm() handler throws. Retries are performed using exponential backoff starting at a two second delay from the first failure with up to six retries allowed.

Alarms can be used to build distributed primitives, like queues or batching of work atop Durable Objects. Alarms also provide a mechanism to guarantee that operations within a Durable Object will complete without relying on incoming requests to keep the Durable Object alive. For a complete example, refer to Use the Alarms API.

​​ Transactional Storage methods

​​ getAlarm

  • getAlarm() : number | null

    • If there is an alarm set, then return the currently set alarm time in number of milliseconds elapsed since the UNIX epoch. Otherwise, return null.

​​ setAlarm

  • setAlarm(scheduledTimeMsnumber) : void

    • Set the time for the alarm to run at in number of milliseconds elapsed since the UNIX epoch.

​​ deleteAlarm

  • deleteAlarm() : void

    • Unset the alarm if there is a currently set alarm.

    • Calling deleteAlarm() inside the alarm() handler may prevent retries on a best-effort basis, but is not guaranteed.

​​ Handler methods

​​ alarm

  • alarm() : void

    • Called by the system when when a scheduled alarm time is reached.

    • The alarm() handler has guaranteed at-least-once execution and will be retried upon failure using exponential backoff, starting at two second delays for up to six retries. Retries will be performed if the method fails with an uncaught exception.

    • This method can be async.