Struct ChildBuilder 

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

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

Advanced properties of a task can be configured with this builder prior to spawning. This builder uses the typestate pattern to control which properties of the child task that can be configured (by controlling which configuration methods are exposed) based on whether the worker is supervisable or not.

See BuilderState for more information on worker types.

Implementations

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

pub fn on_worker_pool(self) -> Self

Runs this child task on the shared worker pool owned by the topology, instead of the component’s runtime.

Use this for compute-heavy work – encoding, serialization, protocol servers – that shouldn’t contend with the runtime that drives the supervisors and I/O for the topology.

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

Runs this child task on a specific runtime.

Prefer on_worker_pool unless the component owns a runtime of its own.

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 component’s shutdown budget. Set this when the component 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_significant(self, significant: bool) -> Self

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

A component’s supervisor uses AutoShutdown::AnySignificant, so a significant child terminating shuts the component down: the child is not individually restarted. That happens even when the child exits cleanly, so this suits a child the component 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.

Only meaningful for a child that can terminate without being restarted, so setting it alongside RestartType::Permanent has no effect: such a child is always restarted and so never reaches this path.

Defaults to false.

pub async fn spawn(self) -> Result<ChildId, SpawnError>

Spawns the child, returning once the supervisor has started it.

Errors

Returns SpawnError::SupervisorGone if the component’s supervisor isn’t running, or SpawnError::Rejected if it rejected the child (for example, an invalid name). A component’s supervisor is running for the whole of the component’s run, so SupervisorGone in a component indicates that the topology is already being torn down.

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

pub fn with_restart_type(self, restart_type: RestartType) -> Self

Sets the restart type for this child task.

Supervised tasks that are defined through Supervisable default to being restarted permanently, since their structure naturally exposes a mechanism to allow initializing a worker more than once. However, in some cases, it may be desirable to disallow restarting a specific worker and instead treat their exit differently: only restart when the worker exits abnormally, or never restart the worker, and so on.

Defaults to RestartType::Permanent.