actor_lifecycle

Generic teardown helpers for actors that follow the SDK’s “polite stop message” convention. Used by credentials_cache and retry/rate_limiter — both opaque types wrap a Subject whose message variant set includes a Stop constructor that triggers actor.stop() next dispatch.

Lives in a separate module so the same fire-and-forget + monitor- based synchronous teardown lands in exactly one place. Adding a third long-lived actor later (a request-rate limiter, an event- stream demuxer) reuses these directly.

Values

safe_call

</>

pub fn safe_call(
  subject subject: process.Subject(msg),
  waiting timeout_ms: Int,
  sending make_request: fn(process.Subject(reply)) -> msg,
) -> Result(reply, Nil)

A non-crashing replacement for actor.call / process.call.

actor.call panics the caller when the callee has exited or fails to reply within the timeout. That is fine for a supervised callee, but the SDK’s long-lived actors (credentials cache, retry rate-limiter) are unsupervised — a single crashing provider would otherwise take down the consumer’s process on every subsequent call. This variant monitors the callee and selects over both the reply and the DOWN signal, returning Error(Nil) on a dead owner, an immediate DOWN, or a timeout, and Ok(reply) on a normal reply. Callers map Error(Nil) onto their own error shape so the consumer sees a recoverable error, never a panic.

Mirrors gleam_erlang’s internal perform_call, minus the two let assert/panic lines that make the stock call crash.

shutdown_via_stop

</>

pub fn shutdown_via_stop(
  subject: process.Subject(msg),
  stop_message: msg,
) -> Nil

Fire-and-forget teardown: send the supplied Stop message and return immediately. The actor exits on its next dispatch. Safe to call against a dead actor — Erlang silently drops sends to a terminated Pid.

shutdown_via_stop_sync

</>

pub fn shutdown_via_stop_sync(
  subject: process.Subject(msg),
  stop_message: msg,
  timeout_ms: Int,
) -> Result(Nil, Nil)

Synchronous teardown: monitor the owning Pid, send Stop, then wait for the DOWN signal up to timeout_ms. Returns Ok(Nil) on clean exit (already-dead actor short-circuits here too — the subject_owner lookup fails fast). Returns Error(Nil) only on real timeout — i.e. the actor is alive but didn’t exit within the window. The monitor is demonitored on the timeout path so the caller’s mailbox doesn’t accumulate stray DOWN messages.