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 apply to the child that it describes. See BuilderState for the states.

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 method for compute-heavy work that must not compete with the runtime that drives its owner and its I/O. Examples are encoding, serialization, and protocol servers. This method changes only where the task runs. The owner of the child still supervises, shuts down, and restarts the child.

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

Sets an explicit shutdown timeout for this child task.

A closure-based child defaults to five seconds, after which it is halted. Set this if a particular child needs more time to drain, or must be halted sooner. A timeout longer than its owner’s has no effect, since the child is halted along with its owner.

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 needed(self) -> Self

Marks this child as one that its owner cannot work without.

If the child stops without a request to stop and can only be started once, its owner also stops and fails. This occurs even when the child exits cleanly. Thus, use this method for a child that its owner cannot work without. Do not use it for a child that you expect to finish by itself. If the child can be started again, its owner restarts it after any such stop, not only after a failure.

For example, one failed connection is usually not a reason to stop a component that handles client connections. But a component that forwards work to a child task can become inoperable if that task stops unexpectedly. This occurs if the task cannot be attached again to the necessary channels or state unless the component is created again.

See the runtime documentation for the default.

pub fn hosted(self) -> Self

Marks this child as one that its owner runs but does not need.

If the child stops without a request to stop, and its owner does not restart it, the owner reaps the child and continues. The owner does not restart a child that can only be started once, or a child that exited cleanly. If the child can be started again, its owner restarts it only if it failed, and accepts a clean exit as final. But if the child fails more often than the restart limit of its owner allows, the owner also fails, as for a needed child.

See the runtime documentation for the default.

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

👎Deprecated:

mark the child needed instead, which stops its owner when it terminates for good

Sets whether the supervisor stops when this child task terminates.

This setting has an effect only under a supervisor that uses the deprecated with_auto_shutdown. It also has no effect on a child that its supervisor always restarts, such as a child that can start again and that you declare with Supervisor::add_worker without marking it hosted. The supervisor logs a warning for each child where the setting has no effect.

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

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

Use this method to register a configured child on a supervisor that has not started yet. The supervisor starts this child when it runs. When the supervisor restarts, the child restarts with it. To start a child now, use spawn.

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.

A builder that was created from a SupervisorHandle spawns the child onto that supervisor. Other builders make the child a child of the current process, and the scope of that process holds it. See spawn.

Returns the ChildId of the child. This method queues the child and does not start it synchronously. Thus, when this method returns, the child can still be in the queue. If its owner does not run, or stops before it processes the child, the child never runs.

Panics

Panics if this builder does not target a specific supervisor and code outside supervision calls this method. See spawn.

pub fn spawn_sibling(self) -> ChildId

Spawns the child onto the ambient supervisor, the nearest supervisor above the current process.

The child is a sibling of the current process only if a supervisor runs that process directly. For a process that runs in a scope, the child goes to the nearest supervisor above it instead. See spawn_sibling.

A builder that was created from a SupervisorHandle spawns the child onto that supervisor, exactly as spawn does.

Panics

Panics if this builder does not target a specific supervisor and there is no ambient supervisor.

pub fn spawn_in(self, scope: &Scope) -> ChildId

Spawns the child into scope.

pub fn spawn_or_detached(self) -> Option<ChildId>

Spawns the child into the scope of the current process, or as a detached task outside supervision.

Returns the ChildId of the child, or None if there was no current scope and the child started as a detached task instead. A detached child never receives a shutdown signal, and nothing restarts it or waits for it. This is how the same work runs without supervision at all. Thus, this method is the correct choice for code that can be called from any location, such as a primitive that a test can construct.

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

pub fn transient(self) -> Self

👎Deprecated:

mark the child hosted instead, which restarts it only if it fails

Restarts this child task only when it terminates abnormally.

pub fn temporary(self) -> Self

👎Deprecated:

implement Supervisable::can_restart instead, if the child can only be started once

Never restarts this child task.