Concurrency / Coroutines

Run work concurrently to call several APIs, race model providers, or process a batch of items. Restate records durable results and coordinates replay so your handler can recover after a failure.

Use Promises to run individual durable operations or calls to other handlers concurrently.
Use Durable Coroutines when each concurrent task contains multiple durable steps that should run in the same handler, for example to share local clients and connections.

Concurrency with Promises

Parallelizing tasks

Start multiple durable operations concurrently by calling them without immediately awaiting:

const call1 = ctx.run("fetch_user", async () =>
  fetchUserData({ userId: 123 })
);
const call2 = ctx.run("fetch_orders", async () =>
  fetchOrderHistory({ userId: 123 })
);
const call3 = ctx
  .serviceClient(analyticsService)
  .calculateMetrics({ userId: 123 });

const user = await call1;
const orders = await call2;
const metrics = await call3;

Check out the guide on parallelizing work.

Retrieving results

Restate provides several patterns for coordinating concurrent tasks. All patterns use RestatePromise combinators that log the order of completion, ensuring deterministic behavior during replays.

Wait for all tasks to complete

Similar to Promise.all, waits for all promises to resolve successfully:

// import { RestatePromise } from "@restatedev/restate-sdk";
const sleepPromise = ctx.sleep({ milliseconds: 100 });
const callPromise = ctx.serviceClient(myService).myHandler("Hi");
const externalCallPromise = ctx.run(() => httpCall());

const resultArray = await RestatePromise.all([
  sleepPromise,
  callPromise,
  externalCallPromise,
]);

Wait for the first successful completion

Similar to Promise.any, returns the first promise that resolves successfully:

const sleepPromise1 = ctx.sleep({ milliseconds: 100 });
const sleepPromise2 = ctx.sleep({ milliseconds: 200 });
const callPromise = ctx.serviceClient(myService).myHandler("Hi");

const firstResult = await RestatePromise.any([
  sleepPromise1,
  sleepPromise2,
  callPromise,
]);

Wait for the first to complete

Similar to Promise.race, returns the first promise to settle (resolve or reject):

const sleepPromise3 = ctx.sleep({ milliseconds: 100 });
const callPromise2 = ctx.serviceClient(myService).myHandler("Hi");

const firstToComplete = await RestatePromise.race([
  sleepPromise3,
  callPromise2,
]);

Wait for all to settle

Similar to Promise.allSettled, waits for all promises to complete regardless of success or failure:

const sleepPromise4 = ctx.sleep({ milliseconds: 100 });
const callPromise3 = ctx.serviceClient(myService).myHandler("Hi");
const externalCallPromise2 = ctx.run(() => httpCall());

const allResults = await RestatePromise.allSettled([
  sleepPromise4,
  callPromise3,
  externalCallPromise2,
]);

Creating already-completed promises

You can create RestatePromise instances that are already resolved or rejected, mirroring Promise.resolve and Promise.reject:

const resolvedPromise = RestatePromise.resolve("already done");

const rejectedPromise = RestatePromise.reject(
  new restate.TerminalError("Access denied", { errorCode: 403 })
);

These are useful when you want to return an already-known value from a function that returns a RestatePromise.

Detecting RestatePromises

Use isRestatePromise to check whether a value is a RestatePromise before using it with combinators like RestatePromise.all():

const somePromise = ctx.sleep({ milliseconds: 100 });
if (isRestatePromise(somePromise)) {
  // safe to use RestatePromise combinators like .all(), .race(), etc.
  await RestatePromise.all([somePromise]);
}

Durable Coroutines

Durable Coroutines let you run concurrent tasks that each contain multiple durable steps within one handler. Each coroutine can pause while waiting for a result, let other coroutines make progress, and resume after failures through replay. Use them when your application benefits from keeping concurrent work in the same process. For example, an agent can run several tools, each with a guardrail check followed by an API call, while sharing local clients and connections. Or it can coordinate background work with steering input and approvals.

Install the coroutine package

Install the coroutine package alongside the TypeScript SDK:

npm install @restatedev/restate-sdk-gen

Using an existing SDK handler

Call execute(ctx, operation) from your handler to run a coroutine. It returns a promise with the result, so you can await it alongside your existing handler logic. This works in Services, Virtual Objects, and Workflows:

import * as sdk from "@restatedev/restate-sdk";
import * as restate from "@restatedev/restate-sdk-gen";

export const existingService = sdk.service({
  name: "ExistingService",
  handlers: {
    summary: async (ctx: sdk.Context, userId: string) =>
      restate.execute(ctx, loadUserSummary(userId)),
  },
});

Here, loadUserSummary is a coroutine that loads a user and their orders. The next section defines it.

Composing durable steps

Coroutines use TypeScript generators (function*). Use gen to describe a routine and yield* to wait for each durable operation. The SDK controls when each generator resumes so it can replay concurrent work consistently. This coroutine loads a user, then their orders:

type UserSummary = { name: string; orderCount: number };

function loadUserSummary(userId: string): Operation<UserSummary> {
  return restate.gen(function* () {
    const user = yield* restate.run(() => fetchUser(userId), {
      name: "fetch-user",
    });
    const orders = yield* restate.run(() => fetchOrders(user.id), {
      name: "fetch-orders",
    });
    return { name: user.name, orderCount: orders.length };
  });
}

fetchUser and fetchOrders stand in for your application APIs. Each call has its own journal entry. yield* pauses the coroutine until a result is available. Keep external I/O and other nondeterministic work inside run. Its callback can use async and await, and receives { signal }, where signal is an AbortSignal you can pass to APIs such as fetch for cancellation. Give each run a name with { name: "fetch-user" }, or pass a named function. Anonymous callbacks require an explicit name.

Call coroutine operations such as run, sleep, and spawn from inside the generator body. Do not call them from a run callback or an unrelated asynchronous callback. As with ctx.run, a run callback must not perform Restate context operations.

Running concurrent coroutines

Use spawn to start a coroutine and get a Task<T> representing its result. This handler starts one coroutine per user and uses all to collect their results in input order:

summaries: async (ctx: sdk.Context, userIds: string[]) =>
  restate.execute(ctx, restate.gen(function* () {
    const tasks = userIds.map((id) => restate.spawn(loadUserSummary(id)));
    return yield* restate.all(tasks);
  })),

Each coroutine runs a set of durable steps. All coroutines execute within the same invocation. Coroutines can share local resources, but those resources are not automatically persisted. Recreate connections, clients, and caches after a restart.

Operations and futures

The coroutine API distinguishes between a description of work and work that has started:

Type	Behavior	How to use it
`Operation<T>`	Lazy. `gen` creates a fresh generator each time you execute the operation.	Use `yield*` to run it in the current coroutine, or `spawn` to start a concurrent coroutine. Executing it again repeats its body.
`Future<T>`	Remembers its outcome. Primitives such as `run` and `sleep` start eagerly and return futures.	Use `yield*` to retrieve the result. You can yield the same future more than once without repeating the work.
`Task<T>`	A future returned by `spawn`, with an additional `interrupt` method.	Wait for the coroutine’s result or interrupt it.

A raw generator instance can only be consumed once. Use gen with a generator factory when you want to execute the same operation again. Use the coroutine combinators for these futures, rather than native Promise combinators. For a group of individual side effects, create run futures and pass them directly to all. Use spawn when each task consists of multiple steps, as in loadUserSummary.

Combining results

Use these combinators inside a coroutine. They accept futures from durable operations, spawned coroutines, or a mix of both.

Wait for all results

all returns results in input order. If an input fails, it throws that error. This example runs two side effects concurrently:

const user = restate.run(() => fetchUser(userId), { name: "fetch-user" });
const orders = restate.run(() => fetchOrders(userId), {
  name: "fetch-orders",
});
const [userData, orderList] = yield* restate.all([user, orders]);

Wait for the first result

race returns the first result or throws the first error. To also identify which branch finished, use select:

const tasks = userIds.map((id) => restate.spawn(loadUserSummary(id)));
const first = yield* restate.race(tasks);

Wait for the first successful result

any returns the first successful result, even if other inputs fail. If every input fails, it throws an AggregateError containing their errors:

const tasks = userIds.map((id) => restate.spawn(loadUserSummary(id)));
const firstSuccessful = yield* restate.any(tasks);

Wait for all results and errors

allSettled waits for every input and returns its outcome in input order. Each entry has either status: "fulfilled" and a value, or status: "rejected" and a reason:

const tasks = userIds.map((id) => restate.spawn(loadUserSummary(id)));
const results = yield* restate.allSettled(tasks);

Identify which branch finished first

select returns the tag and future of the first branch to finish. The tag is the key you gave that branch: "first" or "second" in this example. Switch on winner.tag to handle each branch, then yield its future to retrieve the result or throw its error:

const winner = yield* restate.select({
  first: restate.spawn(loadUserSummary(firstId)),
  second: restate.spawn(loadUserSummary(secondId)),
});
switch (winner.tag) {
  case "first":
    return { tag: "first", summary: yield* winner.future };
  case "second":
    return { tag: "second", summary: yield* winner.future };
}

race, any, and select do not interrupt losing coroutines. They can continue while the main operation runs. See Coroutine lifetime for what happens when it finishes.

Timeouts

Inside a coroutine, use select with a durable timer to limit how long you wait for a result. Here, budgetSeconds sets the timeout, and winner.tag is "done" when the summary finishes first, or "timeout" when the timer finishes first:

const summary = restate.spawn(loadUserSummary(userId));
const winner = yield* restate.select({
  done: summary,
  timeout: restate.sleep({ seconds: budgetSeconds }),
});
if (winner.tag === "timeout") {
  throw new TerminalError("Loading the summary timed out");
}
return yield* winner.future;

This limits how long the handler waits for the summary. It does not undo external work that has already started. A losing coroutine can continue while the main operation is running; the default execution behavior abandons it when the main operation finishes. Use contextLocal to share values such as a request ID or tenant with nested helpers and spawned coroutines, without passing them through every function. Define the storage at module scope, then read and write it inside generator code. This helper reads the request ID before calling an external audit service:

const requestId = restate.contextLocal<string>("unknown");

function loadAuditedSummary(userId: string): Operation<UserSummary> {
  return restate.gen(function* () {
    const id = requestId.get();
    yield* restate.run(() => recordAudit(id, userId), { name: "audit" });
    return yield* loadUserSummary(userId);
  });
}

Inside the main coroutine, set the request ID from the input before spawning the coroutines:

requestId.set(id);
const tasks = userIds.map((userId) =>
  restate.spawn(loadAuditedSummary(userId))
);
return yield* restate.all(tasks);

All coroutines in one execute call share the value. Separate calls have their own storage, even in the same process. get() returns the supplied default until you call set, or undefined if you did not supply a default. Context local values live in memory. Set them from input or a journaled result so replay reconstructs the same values. Use durable state for values that must persist across invocations.

Call get and set in generator code, outside run callbacks. The value is shared by all coroutines in that execution, so a later set changes what the other coroutines read.

Errors and retries

run uses the SDK’s error handling and retries. Configure retries through its retry option, using fields such as maxAttempts, maxDuration, and initialInterval. When the retry policy is exhausted, the operation throws a TerminalError at yield*. Use try/catch around yield* to handle a failure or perform compensation with additional durable steps. Throw a TerminalError from the callback for failures that should not be retried. See the Sagas guide for compensation patterns.

Coroutine lifetime

By default, execution finishes when the main operation returns or throws, both for generator handlers and when using execute. Any unfinished spawned coroutines are abandoned: they are no longer resumed, and their catch and finally blocks do not run. Durable work already performed remains in the journal. To ensure a coroutine finishes, yield its task before returning, as all(tasks) does above. Alternatively, pass { onMainExit: "join" } as the third argument to execute to wait for all spawned coroutines. With this option, a coroutine waiting indefinitely also keeps the handler running indefinitely.

A spawned coroutine is not guaranteed to complete after the main operation finishes. For work that must continue independently of this invocation, use a one way service call.

Interrupting a coroutine

Call task.interrupt() to throw an InterruptedError at the coroutine’s next yield point and abort the signal passed to its active run callback. Pass that signal to external APIs that support cancellation, otherwise the external I/O can continue. You can pass a custom error to interrupt(error) to throw that error instead. Interruption also propagates to coroutines spawned by that task, and the coroutine can catch the error to perform cleanup or recover. After interrupting, yield the task and handle its error to let its cleanup run. Interrupting and immediately returning from the main operation can abandon the task before its catch or finally executes. In this example, the task records an audit entry in finally before the caller catches the interruption:

const work = restate.gen(function* () {
  try {
    yield* restate.sleep({ minutes: 1 });
  } finally {
    yield* restate.run(() => recordAudit("cleanup", userId), {
      name: "cleanup",
    });
  }
});
const task = restate.spawn(work);

task.interrupt();
try {
  yield* task; // Wait for the finally block to finish.
} catch (error) {
  if (!(error instanceof restate.InterruptedError)) throw error;
}

Cooperative cancellation with a stop channel

Use a stop channel to let a coroutine finish its current work and return partial results. This worker checks for a stop before each summary:

function summarizeUntilStopped(
  userIds: string[],
  stop: restate.Channel<void>
): Operation<UserSummary[]> {
  return restate.gen(function* () {
    const results: UserSummary[] = [];
    for (const userId of userIds) {
      const next = yield* restate.select({
        stop: stop.receive,
        ready: restate.sleep({ milliseconds: 100 }),
      });
      if (next.tag === "stop") break;
      results.push(yield* loadUserSummary(userId));
    }
    return results;
  });
}

next.tag identifies whether the stop request or delay finished first. The main coroutine below sends a stop when winner.tag is "timeout", then yields the worker so it can finish:

const stop = restate.channel<void>();
const worker = restate.spawn(summarizeUntilStopped(userIds, stop));
const winner = yield* restate.select({
  done: worker,
  timeout: restate.sleep({ seconds: budgetSeconds }),
});
if (winner.tag === "timeout") {
  yield* stop.send();
}
return yield* worker;

Stopping is cooperative, meaning the current summary can finish, so the budget is not a strict deadline. A channel resolves once and stays resolved. It is shared only within this invocation and reconstructed during replay. For stop requests from other handlers or systems, use an external event, then send on the local channel.

Using other Restate features

Inside a coroutine, use these functions for common Restate operations:

client and sendClient call other Services, Virtual Objects, and Workflows.
state and sharedState access durable state from handlers with the corresponding state access permissions.
awakeable creates an awakeable, a convenient shorthand for a one shot signal with a generated ID that can be completed through the SDK or Restate HTTP API.
workflowPromise accesses a named workflow promise, resolved once and retrievable during workflow retention.

See the API source for API definitions, retry options, and ingress clients. For more examples, follow the coroutine tutorial, including retries, compensation, state, and service calls.

Generator handlers

You can also write a whole handler as a coroutine, without calling execute yourself.

Getting started with generator handlers

Follow the TypeScript prerequisites. For a new project, start with the template:

npx @restatedev/restate example typescript-hello-world-gen

For an existing project, install the coroutine package alongside the TypeScript SDK:

npm install @restatedev/restate-sdk @restatedev/restate-sdk-gen

Defining generator handlers

Use the coroutine package’s service helper to define generator handlers. Operation<T> describes the handler’s result type, and yield* waits for a durable operation and retrieves its result:

export const userService = restate.service({
  name: "UserService",
  handlers: {
    *greet(userId: string): Operation<string> {
      const user = yield* restate.run(() => fetchUser(userId), {
        name: "fetch-user",
      });
      return `Hello, ${user.name}!`;
    },
  },
});

Here, fetchUser represents your API or database call. run records its result, like ctx.run, so completed calls are not repeated during replay. Serve it with serve from @restatedev/restate-sdk, and register it as described in Serving. Use restate.object and restate.workflow in the same way to define Virtual Objects and Workflows with generator handlers.

SDKs

Services

Restate Cloud / BYOC / OSS

References

Concurrency / Coroutines

Concurrency with Promises

Parallelizing tasks

Retrieving results

Wait for all tasks to complete

Wait for the first successful completion

Wait for the first to complete

Wait for all to settle

Creating already-completed promises

Detecting RestatePromises

Durable Coroutines

Install the coroutine package

Using an existing SDK handler

Composing durable steps

Running concurrent coroutines

Operations and futures

Combining results

Wait for all results

Wait for the first result

Wait for the first successful result

Wait for all results and errors

Identify which branch finished first

Timeouts

Errors and retries

Coroutine lifetime

Interrupting a coroutine

Cooperative cancellation with a stop channel

Using other Restate features

Generator handlers

Getting started with generator handlers

Defining generator handlers

​Concurrency with Promises

​Parallelizing tasks

​Retrieving results

​Wait for all tasks to complete

​Wait for the first successful completion

​Wait for the first to complete

​Wait for all to settle

​Creating already-completed promises

​Detecting RestatePromises

​Durable Coroutines

​Install the coroutine package

​Using an existing SDK handler

​Composing durable steps

​Running concurrent coroutines

​Operations and futures

​Combining results

​Wait for all results

​Wait for the first result

​Wait for the first successful result

​Wait for all results and errors

​Identify which branch finished first

​Timeouts

​Sharing values between coroutines

​Errors and retries

​Coroutine lifetime

​Interrupting a coroutine

​Cooperative cancellation with a stop channel

​Using other Restate features

​Generator handlers

​Getting started with generator handlers

​Defining generator handlers

Concurrency with Promises

Parallelizing tasks

Retrieving results

Wait for all tasks to complete

Wait for the first successful completion

Wait for the first to complete

Wait for all to settle

Creating already-completed promises

Detecting RestatePromises

Durable Coroutines

Install the coroutine package

Using an existing SDK handler

Composing durable steps

Running concurrent coroutines

Operations and futures

Combining results

Wait for all results

Wait for the first result

Wait for the first successful result

Wait for all results and errors

Identify which branch finished first

Timeouts

Sharing values between coroutines

Errors and retries

Coroutine lifetime

Interrupting a coroutine

Cooperative cancellation with a stop channel

Using other Restate features

Generator handlers

Getting started with generator handlers

Defining generator handlers