Struct r3::kernel::Task [−][src]
#[repr(transparent)]pub struct Task<System>(_, _);
Expand description
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
Construct a CfgTaskBuilder
to define a task in a configuration
function.
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
.
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).
Start the execution of the task.
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
.
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
.
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
.
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
.
Get the task’s base priority.
The task shouldn’t be in the Dormant state. Otherwise, this method will
return GetTaskPriorityError::BadObjectState
.
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
.