Struct ChildBuilder 

pub struct ChildBuilder<'a, S = OneShot> { /* private fields */ }

Builder for a yet-to-be-started child task.

This is the only way to configure a child: ChildSpecification, which this produces, carries no settings of its own. The builder uses the typestate pattern to expose only the properties that make sense for the child being described, so an invalid combination doesn’t need rejecting at runtime because it can’t be written down. Two axes govern that: whether the worker can be initialized more than once (which decides whether a restart policy is offered), and whether its policy lets it terminate for good (which decides whether it can be marked significant).

See BuilderState and CanTerminate for the states themselves.

Implementations

impl<'a, S: BuilderState> ChildBuilder<'a, S>

pub fn on_runtime(self, handle: Handle) -> Self

Runs this child task on a specific runtime.

Use this for compute-heavy work – encoding, serialization, protocol servers – that shouldn’t contend with the runtime driving the supervisor and its I/O. Only where the task runs changes: the child is still supervised here, and is still shut down and restarted by this supervisor.

pub fn with_shutdown_timeout(self, timeout: Duration) -> Self

Sets an explicit shutdown timeout for this child task.

By default a closure-based child has no deadline of its own and is bounded only by the supervisor’s shutdown budget. Set this when the supervisor wants a particular child abandoned sooner than that – a deadline it is deliberately imposing, rather than a guess at how long the child ought to take. A value longer than the budget has no effect, since the two are resolved to whichever elapses first.

For a Supervisable child, this overrides the strategy the task reports for itself.

pub fn with_shutdown_strategy(self, strategy: ShutdownStrategy) -> Self

Sets the explicit shutdown strategy used for this child task.

pub fn with_budget_bounded_shutdown(self) -> Self

Gives this child no shutdown deadline of its own, leaving it bounded solely by the supervisor’s shutdown budget.

This is already the default for a closure-based child. A Supervisable child reports its own strategy, so this is how one opts into being bounded as part of the group instead – without which it silently keeps whatever Supervisable::shutdown_strategy returns, which may be far shorter than the budget.

See Supervisor::with_shutdown_budget for what the budget itself is.

pub fn build(self) -> ChildSpecification<WorkerSpec>

Finishes describing the child without starting it, for Supervisor::add_worker.

Use this to register a configured child on a supervisor that hasn’t started yet; a child described this way is started when the supervisor runs, and restarted with it. spawn is the counterpart for a supervisor that is already running.

Whichever supervisor this builder was created against is irrelevant here – the child belongs to whichever one it is handed to.

pub fn spawn(self) -> ChildId

Spawns the child.

Returns the child’s ChildId. The child is queued for the supervisor rather than started synchronously, so it may not be running yet by the time this returns; if the supervisor isn’t running, or shuts down before reaching the child, it never runs at all.

Panics

If this builder targets the ambient supervisor and there isn’t one, this panics. See spawn.

impl<'a, S: CanTerminate> ChildBuilder<'a, S>

pub fn with_significant(self, significant: bool) -> Self

Sets whether this child task’s termination should stop the supervisor.

Under AutoShutdown::AnySignificant – which is what a topology component’s supervisor uses – a significant child terminating shuts the supervisor down: the child is not individually restarted. That happens even when the child exits cleanly, so this suits a child the supervisor cannot function without, and not one that is expected to finish on its own.

For example, a component handling client connections generally shouldn’t stop just because one connection failed, but a component forwarding work to a child task may become inoperable if that task dies and cannot be reattached to the necessary channels or state without recreating the component.

Offered only for a child that can actually terminate for good – a one-shot child, or a supervisable one narrowed with transient or temporary. A permanent child is always restarted and so never reaches this path, which makes marking one significant a contradiction rather than a setting.

Defaults to false.

impl<'a> ChildBuilder<'a, Restartable>

pub fn transient(self) -> ChildBuilder<'a, Terminable>

Restarts this child task only when it terminates abnormally.

A clean exit is taken at face value and the child stays stopped; a failure is restarted. Use this for work that has a natural end but whose failure means it never got there.

Narrows the restart policy to RestartType::Transient, which makes with_significant available: a child that can stop for good is one whose termination the supervisor may want to act on.

pub fn temporary(self) -> ChildBuilder<'a, Terminable>

Never restarts this child task.

However it terminates – cleanly or by failing – the child stays stopped. Use this for work that is meant to run once, where a retry would be wrong rather than merely redundant.

Narrows the restart policy to RestartType::Temporary, which makes with_significant available: a child that can stop for good is one whose termination the supervisor may want to act on.