timer

Durable workflow timers over canonical Duration values.

Types

TimerRef

opaque </>

A reference to a named durable timer started by workflow code.

The reference carries the author-supplied named timer identifier returned by the engine. Anonymous sleeps deliberately do not expose a TimerRef because AT only permits named timers to be cancelled independently.

pub opaque type TimerRef

Values

cancel_timer

</>

pub fn cancel_timer(
  reference: TimerRef,
) -> Result(Nil, error.EngineError)

Cancel a named durable timer.

AT treats cancelling an already-fired or already-cancelled named timer as an idempotent no-op, so a successful engine response is always returned as Ok(Nil). Anonymous sleeps cannot be cancelled through this function because they never produce a TimerRef.

sleep

</>

pub fn sleep(
  duration: duration.Duration,
) -> Result(Nil, error.EngineError)

Wait for an anonymous durable timer to fire.

The timer is durable: it survives engine restart and, during replay, returns instantly once the matching timer-fired event is already present in history. Anonymous sleeps are not separately cancellable; cancelling a sleep means cancelling the workflow that is blocked on it (AT D3). Use start_timer when workflow code needs a named timer that can be cancelled independently. The await is a yield point: pending workflow queries are serviced by the query pump while the timer is parked. with_timeout needs no pump of its own — the awaits running inside its operation are the yield points.

start_timer

</>

pub fn start_timer(
  name: String,
  duration: duration.Duration,
) -> Result(TimerRef, error.EngineError)

Start a named durable timer and return its cancellable reference.

The supplied name is the named timer identifier handed to AT. The SDK does not invent a default duration or rewrite the identifier; engine-side timer ID validation remains authoritative.

timer_id

</>

pub fn timer_id(reference: TimerRef) -> String

Return the engine timer identifier carried by a named timer reference.

with_timeout

</>

pub fn with_timeout(
  operation: fn() -> Result(value, inner_error),
  deadline: duration.Duration,
) -> Result(value, error.TimeoutResultError(inner_error))

Run an awaiting operation with a durable deadline.

The operation is a thunk so the engine/test FFI can establish the timeout before the await begins. If the operation completes before the deadline its Ok value is returned. If the operation returns its own typed error, that error is wrapped in InnerError. If AT reports that the deadline expired (the engine’s timeout:-tagged result), the result is TimedOutError(TimedOut(...)). Any other engine error is surfaced as TimeoutEngineFailure — an infrastructure fault must never be mistaken for a deadline expiry.