Temporal Timer

Durable Timers are one of the features provided by Temporal and are used to introduce delays in a Workflow Execution. When a Timer is set, the execution of code awaiting that timer will block until the Timer fires. Timers are maintained by the Temporal Cluster and the Worker does not consume resources while awaiting them.

The duration of a Timer is fixed and can range from one second to several years. Although it is possible to specify a duration of less than one second, you should avoid doing so because the networking latency involved with roundtrips between the Worker and Temporal Cluster will affect the precision of Timers with sub-second durations.

Use cases

There are several reasons that you might want to introduce delays in a Workflow Execution.

One is that your business logic dictates that you execute an Activity at fixed intervals. For example, a Workflow used for customer onboarding might send e-mail reminders one day, one week, and/or one month after they sign up.

Another is that you need to execute an Activity multiple times at intervals that are dynamically calculated. In this case, you might delay calling one Activity based on the value returned by a previous Activity.

Yet another reason is that you need to allow time for offline steps to complete before proceeding. For example, a business process may require a fixed period of time to elapse before the next task can begin.

SDK API

Pause Workflow

You should NOT use Thread.sleep or java.util.Timer, instead use:

import java.time.Duration;
import io.temporal.workflow.Workflow;
 
// This will pause Workflow Execution for 10 seconds
Workflow.sleep(Duration.ofSeconds(10));

It’s Workflow safe replacement for Java’s Thread.sleep.

Running code at a specific point in the future

import java.time.Duration;
import io.temporal.workflow.Workflow;
 
// Workflow.newTimer is a Workflow-safe counterpart to java.util.Timer
Promise timerPromise = Workflow.newTimer(Duration.ofSeconds(30))
logger.info("The timer was set")
 
// Unlike Workflow.sleep, waiting for the timer is a separate operation
timerPromise.get()
logger.Info("The timer has fired")

This is a Workflow-safe replacement for Java’s java.util.Timer class. It takes the duration to wait as a parameter, the same two input parameters as Workflow.sleep, but unlike that method, calling it does not block after setting the Timer. Instead, it returns a Promise, which becomes ready when the Timer fires (or is canceled). Waiting on that Promise will block until it becomes ready.

Timers are durable and are maintained by the Temporal Cluster. When the Worker encounters either a Workflow.sleep or Workflow.newTimer call in the Workflow code, it submits a request to the cluster, asking it to start a Timer for the specified duration. When the Timer fires, the cluster adds a new Workflow Task to the Task Queue, after which the Worker resumes execution of the Workflow.

Caution

Be sure to note that the cluster fires the Timer after the specified duration, regardless of whether or not any Workers happen to be running at the time. To better understand the behavior of a Timer in the event of a Worker crash, consider the following scenario: Your Workflow code uses Workflow.sleep to set a Timer for 10 seconds and you have a single Worker process, which happens to crash 3 seconds later.

• If you restart the Worker process 2 seconds later, then Workflow Execution will pause for the remaining 5 seconds of the Timer, and it will be as if it had never crashed at all
• However, if you started it 20 minutes later, then the Timer will have already fired, and the Worker will resume execution of the remaining Workflow code without additional delay

Since Timers are maintained by the Temporal Cluster, they fire regardless of whether any Workers are running. However, as suggested by the second bullet point, Workers can experience potentially long outages, whether due to a crash or system maintenance. Therefore, Workflow code should be robust to account for the possibility that a Timer takes longer than the specified duration.