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 Storage API, and alarm operations follow the same rules as other storage operations.

Notably:

• Each Durable Object 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 2 second delay from the first failure with up to 6 retries allowed.

How are alarms different from Cron Triggers?

Alarms are more fine grained than Cron Triggers. A Worker can have up to three Cron Triggers configured at once, but it can have an unlimited amount of Durable Objects, each of which can have an alarm set.

Alarms are directly scheduled from within your Durable Object. Cron Triggers, on the other hand, are not programmatic. Cron Triggers execute based on their schedules, which have to be configured through the Cloudflare dashboard or API.

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.

Storage methods

getAlarm

• getAlarm(): number | null

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

setAlarm

• setAlarm(scheduledTimeMs number ) : void

  • Set the time for the alarm to run. Specify the time as the 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(alarmInfoObject )`: void

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

  • The optional parameter alarmInfo object has two properties:

    • retryCount number : The number of times this alarm event has been retried.
    • isRetry boolean : A boolean value to indicate if the alarm has been retried. This value is true if this alarm event is a retry.

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

  • This method can be async.

Example

This example shows how to both set alarms with the setAlarm(timestamp) method and handle alarms with the alarm() handler within your Durable Object.

• The alarm() handler will be called once every time an alarm fires.
• If an unexpected error terminates the Durable Object, the alarm() handler may be re-instantiated on another machine.
• Following a short delay, the alarm() handler will run from the beginning on the other machine.

import { DurableObject } from "cloudflare:workers";

export default {
  async fetch(request, env) {
    let id = env.ALARM_EXAMPLE.idFromName("foo");
    return await env.ALARM_EXAMPLE.get(id).fetch(request);
  },
};

const SECONDS = 1000;

export class AlarmExample extends DurableObject {
  constructor(ctx, env) {
    this.ctx = ctx;
    this.storage = ctx.storage;
  }
  async fetch(request) {
    // If there is no alarm currently set, set one for 10 seconds from now
    let currentAlarm = await this.storage.getAlarm();
    if (currentAlarm == null) {
      this.storage.setAlarm(Date.now() + 10 * SECONDS);
    }
  }
  async alarm() {
    // The alarm handler will be invoked whenever an alarm fires.
    // You can use this to do work, read from the Storage API, make HTTP calls
    // and set future alarms to run using this.storage.setAlarm() from within this handler.
  }
}

The following example shows how to use the alarmInfo property to identify if the alarm event has been attempted before.

class MyDurableObject extends DurableObject {
  async alarm(alarmInfo) {
    if (alarmInfo?.retryCount != 0) {
      console.log("This alarm event has been attempted ${alarmInfo?.retryCount} times before.");
    }
  }
}

Related resources

• Understand how to use the Alarms API in an end-to-end example.
• Read the Durable Objects alarms announcement blog post ↗.
• Review the Storage API documentation for Durable Objects.

Was this helpful?

What did you like?

Accurate

Easy to understand

Solved my problem

Helped me decide to use the product

Other

What went wrong?

Hard to understand

Incorrect information

Missing the information

Other

Thank you for helping improve Cloudflare's documentation!