Struct spawn::TaskBuilder

pub struct TaskBuilder<F, A, R> { /* private fields */ }

A struct that offers a builder pattern to create and customize new Tasks.

Note that the new Task will not actually be created until spawn() is invoked.

To create a TaskBuilder, use these functions:

• new_task_builder(): creates a new task for a known, existing function.
• new_application_task_builder(): loads a new application crate and creates a new task for that crate’s entry point (main) function.

Implementations

impl<F, A, R> TaskBuilder<F, A, R>where A: Send + 'static, R: Send + 'static, F: FnOnce(A) -> R,

pub fn name(self, name: String) -> TaskBuilder<F, A, R>

Set the String name for the new Task.

pub fn argument(self, argument: A) -> TaskBuilder<F, A, R>

Set the argument that will be passed to the new Task’s entry function.

pub fn stack(self, stack: Stack) -> TaskBuilder<F, A, R>

Set the Stack that will be used by the new Task.

pub fn parent(self, parent_task: TaskRef) -> TaskBuilder<F, A, R>

Set the “parent” Task from which the new Task will inherit certain states.

See [Task::new()] for more details on what states are inherited. By default, the current task will be used if a specific parent task is not provided.

pub fn pin_on_cpu(self, cpu_id: CpuId) -> TaskBuilder<F, A, R>

Pin the new Task to a specific CPU.

pub fn block(self) -> TaskBuilder<F, A, R>

Set the new Task’s RunState to be Blocked instead of Runnable when it is first spawned. This allows another task to delay the new task’s execution arbitrarily, e.g., to set up other things for the newly-spawned (but not yet running) task.

Note that the new Task will not be Runnable until it is explicitly set as such.

pub fn spawn(self) -> Result<JoinableTaskRef, &'static str>

Finishes this TaskBuilder and spawns the new task as described by its builder functions.

Synchronizes memory with respect to the spawned task.

This merely creates the new task and makes it Runnable. It does not switch to it immediately; that will happen on the next scheduler invocation.

impl<F, A, R> TaskBuilder<F, A, R>where A: Send + Clone + 'static, R: Send + 'static, F: FnOnce(A) -> R + Send + Clone + 'static,

Additional implementation of TaskBuilder to be used for restartable functions. Further restricts the function (F) and argument (A) to implement Clone trait.

pub fn idle(self, cpu_id: CpuId) -> TaskBuilder<F, A, R>

Sets this new Task to be the idle task for the given CPU.

Idle tasks will not be scheduled unless there are no other tasks for the scheduler to choose.

Idle tasks must be restartable, so it is only a possible option when spawning a restartable task. Marking a task as idle is only needed to set up one for each CPU when that CPU is initialized, but or to restart an idle task that has exited or failed.

There is no harm spawning multiple idle tasks on each CPU, but it’s a waste of space.

pub fn spawn_restartable( self, restart_with_arg: Option<A> ) -> Result<JoinableTaskRef, &'static str>

Like TaskBuilder::spawn(), this finishes this TaskBuilder and spawns the new task. It also stores the new Task’s function and argument within the Task, enabling it to be restarted upon exit.

Arguments

• restart_with_arg: if Some, this argument will be passed into the restarted task instead of the argument initially provided to new_task_builder().

Note that the argument initially provided to new_task_builder() will always be passed into the initially-spawned instance of this task. The restart_with_arg value is only used as an argument for future instances of this task that are re-spawned (restarted) if the initial task exits.

This allows one to spawn a task that is restartable but performs a given action with its initial argument only once. This is typically achieved by using an Option<T> for the argument type A:

• The argument Some(T) is passed into new_task_builder(), such that it is used for and passed to the first spawned instance of this task.
• The argument None is used for restart_with_arg, such that it is used for and passed to the subsequent restarted instances of this task.

This function merely makes the new task Runnable, it does not switch to it immediately; that will happen on the next scheduler invocation.