Struct task::ExitableTaskRef
source · pub struct ExitableTaskRef { /* private fields */ }Expand description
A wrapper around TaskRef that allows this task to mark itself as exited.
This is primarily an internal implementation details, as it is only obtainable
when a task is first switched to, specifically while it is executing the
spawn::task_wrapper() (before it proceeds to running its actual entry function).
Not Clone-able
This type does not implement Clone because it assumes there is
only ever one ExitableTaskRef per task.
However, this type auto-derefs into an inner TaskRef,
which can be cloned, so you can easily call .clone() on it.
Implementations§
source§impl ExitableTaskRef
impl ExitableTaskRef
sourcepub fn mark_as_exited(
&self,
exit_value: Box<dyn Any + Send>
) -> Result<(), &'static str>
pub fn mark_as_exited( &self, exit_value: Box<dyn Any + Send> ) -> Result<(), &'static str>
Call this function to indicate that this task has successfully ran to completion,
and that it has returned the given exit_value.
This is only usable within task cleanup functions to indicate that the current task has cleanly exited.
Return
- Returns
Okif the exit status was successfully set. - Returns
Errif thisTaskwas already exited; the existing exit status will not be overwritten.
Note
The Task will not be halted immediately –
it will finish running its current timeslice, and then never be run again.
sourcepub fn mark_as_killed(&self, reason: KillReason) -> Result<(), &'static str>
pub fn mark_as_killed(&self, reason: KillReason) -> Result<(), &'static str>
Call this function to indicate that this task has been cleaned up (e.g., by unwinding) and it is ready to be marked as killed, i.e., it will never run again.
If you want to kill another task, use TaskRef::kill() instead.
This is only usable within task cleanup functions (e.g., after unwinding) to indicate that the current task has crashed or failed and has been killed by the system.
Return
- Returns
Okif the exit status was successfully set. - Returns
Errif thisTaskwas already exited, and does not overwrite the existing exit status.
Note
The Task will not be halted immediately –
it will finish running its current timeslice, and then never be run again.
sourcepub fn reap_if_orphaned(&self)
pub fn reap_if_orphaned(&self)
Reaps this task (if orphaned) by taking and dropping its exit value and removing it from the system task list.
If this task has not been orphaned, meaning it is still joinable, then this function does nothing.
sourcepub fn post_context_switch_action(&self) -> PreemptionGuard
pub fn post_context_switch_action(&self) -> PreemptionGuard
Perform any actions needed after a context switch.
Currently this only does two things:
- Drops any data that the original previous task (before the context switch) prepared for us to drop after the context switch has completed.
- Obtains the preemption guard such that preemption can be re-enabled when it is appropriate to do so.
Note: this publicly re-exports the private post_context_switch_action()
function for use in the early spawn::task_wrapper functions,
which is the only place where an ExitableTaskRef can be obtained.
Methods from Deref<Target = TaskRef>§
sourcepub fn downgrade(&self) -> WeakTaskRef
pub fn downgrade(&self) -> WeakTaskRef
Creates a new weak reference to this Task, similar to Weak.
sourcepub fn is_joinable(&self) -> bool
pub fn is_joinable(&self) -> bool
Returns true if this task is joinable, false if not.
- If
true, another task holds theJoinableTaskRefobject that was created byTaskRef::create(), which indicates that that other task is able to wait for this task to exit and thus be able to obtain this task’s exit value. - If
false, theJoinableTaskRefobject was dropped, and therefore no other task can join this task or obtain its exit value.
When a task is not joinable, it is considered to be an orphan and will thus be automatically reaped and cleaned up once it exits because no other task is waiting on it to exit.
sourcepub fn kill(&self, reason: KillReason) -> Result<(), &'static str>
pub fn kill(&self, reason: KillReason) -> Result<(), &'static str>
Kills this Task (not a clean exit) without allowing it to run to completion.
The provided KillReason indicates why it was killed.
** Currently this immediately kills the task without performing any unwinding cleanup. In the near future, the task will be unwound such that its resources are freed/dropped to ensure proper cleanup before the task is actually fully killed. **
Locking / Deadlock
This method obtains a writable lock on the underlying Task’s inner state.
Return
- Returns
Okif the exit status was successfully set to the givenKillReason. - Returns
Errif thisTaskwas already exited, and does not overwrite the existing exit status.
Note
The Task will not be halted immediately –
it will finish running its current timeslice, and then never be run again.
Methods from Deref<Target = Task>§
pub fn set_env(&self, new_env: Arc<Mutex<Environment, Spin>, Global>)
pub fn set_env(&self, new_env: Arc<Mutex<Environment, Spin>, Global>)
Sets the Environment of this Task.
Locking / Deadlock
Obtains the lock on this Task’s inner state in order to mutate it.
pub fn get_env(&self) -> Arc<Mutex<Environment, Spin>, Global>
pub fn get_env(&self) -> Arc<Mutex<Environment, Spin>, Global>
Gets a reference to this task’s Environment.
Locking / Deadlock
Obtains the lock on this Task’s inner state in order to access it.
pub fn is_running(&self) -> bool
pub fn is_running(&self) -> bool
Returns true if this Task is currently running.
pub fn running_on_cpu(&self) -> Option<CpuId>
pub fn running_on_cpu(&self) -> Option<CpuId>
Returns the ID of the CPU this Task is currently running on.
pub fn pinned_cpu(&self) -> Option<CpuId>
pub fn pinned_cpu(&self) -> Option<CpuId>
Returns the ID of the CPU this Task is pinned on,
or None if it is not pinned.
pub fn is_runnable(&self) -> bool
pub fn is_runnable(&self) -> bool
pub fn get_namespace(&self) -> &Arc<CrateNamespace, Global>
pub fn get_namespace(&self) -> &Arc<CrateNamespace, Global>
Returns the namespace that this Task is loaded/linked into and runs within.
pub fn with_kstack<R, F>(&self, func: F) -> Rwhere
F: FnOnce(&Stack) -> R,
pub fn with_kstack<R, F>(&self, func: F) -> Rwhere F: FnOnce(&Stack) -> R,
Exposes read-only access to this Task’s [Stack] by invoking
the given func with a reference to its kernel stack.
Locking / Deadlock
Obtains the lock on this Task’s inner state for the duration of func
in order to access its stack.
The given func must not attempt to obtain that same inner lock.
pub fn with_restart_info<R, F>(&self, func: F) -> Rwhere
F: FnOnce(Option<&RestartInfo>) -> R,
pub fn with_restart_info<R, F>(&self, func: F) -> Rwhere F: FnOnce(Option<&RestartInfo>) -> R,
Invokes func with immutable access to this Task’s RestartInfo.
Locking / Deadlock
Obtains the lock on this Task’s inner state for the duration of func
in order to access its stack.
The given func must not attempt to obtain that same inner lock.
pub fn has_exited(&self) -> bool
pub fn has_exited(&self) -> bool
Returns true if this Task has been exited, i.e.,
if its RunState is either Exited or Reaped.
pub fn is_application(&self) -> bool
pub fn is_application(&self) -> bool
Returns true if this is an application Task.
This will also return true if this task was spawned by an application task,
since a task inherits the “application crate” field from its “parent” that spawned it.
pub fn is_restartable(&self) -> bool
pub fn is_restartable(&self) -> bool
Returns true if this Task was spawned as a restartable task.
Locking / Deadlock
Obtains the lock on this Task’s inner state in order to access it.
pub fn block(&self) -> Result<RunState, RunState>
pub fn block(&self) -> Result<RunState, RunState>
Blocks this Task by setting its runstate to RunState::Blocked.
Returns the previous runstate on success, and the current runstate on error. This will only succeed if the task is runnable or already blocked.
pub fn block_initing_task(&self) -> Result<RunState, RunState>
pub fn block_initing_task(&self) -> Result<RunState, RunState>
Blocks this Task if it is a newly-spawned task currently being initialized.
This is a special case only to be used when spawning a new task that should not be immediately scheduled in; it will fail for all other cases.
Returns the previous runstate (i.e. RunState::Initing) on success,
or the current runstate on error.
pub fn unblock(&self) -> Result<RunState, RunState>
pub fn unblock(&self) -> Result<RunState, RunState>
Unblocks this Task by setting its runstate to RunState::Runnable.
Returns the previous runstate on success, and the current runstate on error. Will only succed if the task is blocked or already runnable.
pub fn make_inited_task_runnable(&self) -> Result<RunState, RunState>
pub fn make_inited_task_runnable(&self) -> Result<RunState, RunState>
Makes this Task Runnable if it is a newly-spawned and fully initialized task.
This is a special case only to be used when spawning a new task that is ready to be scheduled in; it will fail for all other cases.
Returns the previous runstate (i.e. RunState::Initing) on success, and
the current runstate on error.
pub fn suspend(&self)
pub fn suspend(&self)
Suspends this Task.
pub fn unsuspend(&self)
pub fn unsuspend(&self)
Unsuspends this Task.
pub fn is_suspended(&self) -> bool
pub fn is_suspended(&self) -> bool
Returns true if this Task is suspended.
Note that a task being suspended is independent from its RunState.