gracefulStop

gracefulStop(ref, timeoutMs): Promise<boolean>

Defined in: src/pattern/GracefulStop.ts:48

Stop ref after it has worked through its mailbox, and wait for it.

ActorRef.stop() already means stop-after-drain — it sends a PoisonPill, an ordinary user message that is therefore ordered behind everything already queued — but it is fire-and-forget, and outside an actor there is no watch to learn when the stop actually happened (#663). This is that missing half:

const stopped = await gracefulStop(worker, 5_000);

Resolves true once the actor is confirmed terminated. If timeoutMs elapses first it resolves false — and escalates, enqueueing the system terminate that jumps the user queue, so a caller who has run out of patience is not also left with a live actor. What was still queued goes to dead letters, exactly as any other hard stop.

Why false and not a rejection. A stop that timed out is an outcome, not an error: the caller asked for a bounded stop and got one, and the two answers differ only in whether the mailbox was finished. Rejecting would make the ordinary “shut this down within five seconds, whatever it takes” call site need a try/catch to express what a boolean says.

The budget is a required argument. A graceful stop’s whole content is the bound, and a default one would be the number that silently truncated somebody’s shutdown.

Only a locally-hosted actor can be observed this way — the confirmation comes from its cell’s watcher set. For any other ref (a cluster ref, a router’s remote routee) the stop is still delivered, but there is nothing local to confirm it with, so this resolves false when the budget runs out. Watch it from inside an actor with context.watch(ref) instead.

Parameters

ref

ActorRef

timeoutMs

number

Returns

Promise<boolean>