Crate task

Key types and functions for multitasking that build on the basic Task.

The main types of interest are:

1. TaskRef: a shareable reference to a Task that can actually be used, unlike the basic Task type that cannot be spawned, modified, or scheduled in.
2. JoinableTaskRef: a derivative of TaskRef that allows the owner (a different task) to join that task, i.e., wait for it to exit, and to retrieve its ExitValue.

The main standalone functions allow one to:

1. Obtain the current task:
   • with_current_task() is the preferred way, which accepts a closure that is invoked with access to the current task. This is preferred because it doesn’t need to clone the current task reference and is thus most efficient.
   • get_my_current_task() returns a cloned reference to the current task and is thus slightly more expensive with_current_task().
   • get_my_current_task_id() is fastest if you just want the ID of the current task. Note that it is fairly expensive to obtain a task reference from a task ID.
2. Register a kill handler for the current task – set_kill_handler().
3. Yield the current CPU and schedule in another task – schedule().
4. Switch from the current task to another specific “next” task – task_switch().

To create new task, use the task builder functions in spawn rather than attempting to manually instantiate a TaskRef.

Re-exports

• pub use scheduler::schedule;

Modules

• scheduler

Structs

• CurrentTaskNotFound
  An error type indicating that the current task has not yet been initialized.
• ExitableTaskRef
  A wrapper around TaskRef that allows this task to mark itself as exited.
• JoinableTaskRef
  A reference to a Task that can be joined; auto-derefs into TaskRef.
• PanicInfoOwned
  Just like core::panic::PanicInfo, but with owned String types instead of &str references.
• RestartInfo
  A struct holding data items needed to restart a Task.
• ScheduleOnDrop
  An empty struct that invokes schedule() when it is dropped.
• Task
  A structure that contains contextual information for a thread of execution.
• TaskRef
  A shareable, cloneable reference to a Task that exposes more methods for task management and auto-derefs into an immutable &Task reference.
• WeakTaskRef
  A weak reference to a shared Task reference (TaskRef).

Enums

• ExitValue
  The two ways a Task can exit, including possible return values and conditions.
• InheritedStates
  The states used to initialize a new Task when creating it; see Task::new().
• InitCurrentTaskError
  An error type indicating that the current task was already initialized.
• KillReason
  The list of possible reasons that a given Task was killed prematurely.
• RunState
  The set of possible runstates that a Task can be in.

Functions

• all_tasks
  Returns a list containing a snapshot of all tasks that currently exist.
• bootstrap_task
  Bootstraps a new task from the current thread of execution.
• get_my_current_task
  Returns a cloned reference to the current task.
• get_my_current_task_id
  Returns the unique ID of the current task.
• get_task
  Returns a WeakTaskRef (shared reference) to the Task specified by the given task_id.
• set_kill_handler
  Registers a kill handler function for the current Task.
• take_kill_handler
  Takes ownership of the current Task’s KillHandler function.
• task_switch
  Switches from the current task to the given next task.
• with_current_task
  Invokes the given function with a reference to the current task.
• with_current_task_and_value
  Similar to with_current_task(), but also accepts a value that is passed to the given function or returned in the case of an error.

Type Aliases

• FailureCleanupFunction
  The signature of a Task’s failure cleanup function.
• KillHandler
  The function signature of the callback that will be invoked when a Task panics or otherwise fails, e.g., a machine exception occurs.