Struct r3::kernel::Task

#[repr(transparent)]pub struct Task<System>(_, _);

Represents a single task in a system.

This type is ABI-compatible with Id.

Relation to Other Specifications: Present in almost every real-time operating system.

Task States

A task may be in one of the following states:

• Dormant — The task is not executing, doesn't have an associated execution thread, and can be activated.

• Ready — The task has an associated execution thread, which is ready to be scheduled to the CPU

• Running — The task has an associated execution thread, which is currently scheduled to the CPU

• Waiting — The task has an associated execution thread, which is currently blocked by a blocking operation

Implementations

impl<System: Port> Task<System>

pub const fn build() -> CfgTaskBuilder<System>

Construct a CfgTaskBuilder to define a task in a configuration function.

impl<System> Task<System>

pub const unsafe fn from_id(id: Id) -> Self

Construct a Task from Id.

Safety

The kernel can handle invalid IDs without a problem. However, the constructed Task may point to an object that is not intended to be manipulated except by its creator. This is usually prevented by making Task an opaque handle, but this safeguard can be circumvented by this method.

Constructing a Task for a current task is allowed. This can be safely done by Task::current.

pub const fn id(self) -> Id

Get the raw Id value representing this task.

impl<System: Kernel> Task<System>

pub fn current() -> Result<Option<Self>, GetCurrentTaskError>

Get the current task (i.e., the task in the Running state).

In a task context, this method returns the currently running task.

In an interrupt context, the result is unreliable because scheduling is deferred until the control returns to a task, but the current interrupt handler could be interrupted by another interrrupt, which might do scheduling on return (whether this happens or not is unspecified).

pub fn activate(self) -> Result<(), ActivateTaskError>

Start the execution of the task.

pub fn interrupt(self) -> Result<(), InterruptTaskError>

Interrupt any ongoing wait operations undertaken by the task.

This method interrupt any ongoing system call that is blocking the task. The interrupted system call will return WaitError::Interrupted or WaitTimeoutError::Interrupted.

pub fn unpark(self) -> Result<(), UnparkError>

Make the task's token available, unblocking Kernel::park now or in the future.

If the token is already available, this method will return without doing anything. Use Task::unpark_exact if you need to detect this condition.

If the task is currently being blocked by Kernel::park, the token will be immediately consumed. Otherwise, it will be consumed on a next call to Kernel::park.

pub fn unpark_exact(self) -> Result<(), UnparkExactError>

Make exactly one new token available for the task, unblocking Kernel::park now or in the future.

If the token is already available, this method will return UnparkExactError::QueueOverflow. Thus, this method will succeed only if it made exactly one token available.

If the task is currently being blocked by Kernel::park, the token will be immediately consumed. Otherwise, it will be consumed on a next call to Kernel::park.

pub fn set_priority(self, priority: usize) -> Result<(), SetTaskPriorityError>

Set the task's base priority.

A task's base priority is used to calculate its effective priority. Tasks with lower effective priorities execute first. The base priority is reset to the initial value specified by CfgTaskBuilder::priority upon activation.

The value must be in range 0..num_task_priority_levels. Otherwise, this method will return SetTaskPriorityError::BadParam.

The task shouldn't be in the Dormant state. Otherwise, this method will return SetTaskPriorityError::BadObjectState.

pub fn priority(self) -> Result<usize, GetTaskPriorityError>

Get the task's base priority.

The task shouldn't be in the Dormant state. Otherwise, this method will return GetTaskPriorityError::BadObjectState.

pub fn effective_priority(self) -> Result<usize, GetTaskPriorityError>

Get the task's effective priority.

The effective priority is calculated based on the task's base priority and can be temporarily raised by a mutex locking protocol.

The task shouldn't be in the Dormant state. Otherwise, this method will return GetTaskPriorityError::BadObjectState.

Trait Implementations

impl<System> Clone for Task<System>

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<System> Copy for Task<System>

impl<System> Debug for Task<System>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<System> Eq for Task<System>

impl<System> Hash for Task<System>

fn hash<H>(&self, state: &mut H) where
    H: Hasher, 

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given Hasher.

impl<System> PartialEq<Task<System>> for Task<System>

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]fn ne(&self, other: &Rhs) -> bool

This method tests for !=.