Struct task::TaskRef

source ·
pub struct TaskRef(/* private fields */);
Expand description

A shareable, cloneable reference to a Task that exposes more methods for task management and auto-derefs into an immutable &Task reference.

The TaskRef type is necessary because in many places across Theseus, a reference to a Task is used. For example, task lists, task spawning, task management, scheduling, etc.

Equality comparisons

TaskRef implements the PartialEq and Eq traits to ensure that two TaskRefs are considered equal if they point to the same underlying Task.

Implementations§

source§

impl TaskRef

source

pub fn create( task: Task, failure_cleanup_function: FailureCleanupFunction ) -> JoinableTaskRef

Creates a new TaskRef, a shareable wrapper around the given Task.

This does not add this task to the system-wide task list or any runqueues, nor does it schedule this task in.

Arguments
  • task: the new Task to wrap in a TaskRef.
  • failure_cleanup_function: an error handling function that acts as a last resort when all else fails, e.g., if unwinding fails.
Return

Returns a JoinableTaskRef, which derefs into the newly-created TaskRef and can be used to “join” this task (wait for it to exit) and obtain its exit value.

source

pub fn downgrade(&self) -> WeakTaskRef

Creates a new weak reference to this Task, similar to Weak.

source

pub fn is_joinable(&self) -> bool

Returns true if this task is joinable, false if not.

  • If true, another task holds the JoinableTaskRef object that was created by TaskRef::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, the JoinableTaskRef object 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.

source

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 Ok if the exit status was successfully set to the given KillReason.
  • Returns Err if this Task was 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>)

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>

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

Returns true if this Task is currently running.

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>

Returns the ID of the CPU this Task is pinned on, or None if it is not pinned.

pub fn runstate(&self) -> RunState

Returns the current RunState of this Task.

pub fn is_runnable(&self) -> bool

Returns whether this Task is runnable, i.e., able to be scheduled in.

For this to return true, this Task’s runstate must be Runnable and it must not be suspended.

Note

This does NOT mean that this Task is actually currently running, just that it is able to be run.

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,

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,

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

Returns true if this Task has been exited, i.e., if its RunState is either Exited or Reaped.

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

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>

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>

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>

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>

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)

Suspends this Task.

pub fn unsuspend(&self)

Unsuspends this Task.

pub fn is_suspended(&self) -> bool

Returns true if this Task is suspended.

Note that a task being suspended is independent from its RunState.

Trait Implementations§

source§

impl Clone for TaskRef

source§

fn clone(&self) -> TaskRef

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

impl Debug for TaskRef

source§

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

Formats the value using the given formatter. Read more
source§

impl Deref for TaskRef

§

type Target = Task

The resulting type after dereferencing.
source§

fn deref(&self) -> &Self::Target

Dereferences the value.
source§

impl Hash for TaskRef

source§

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

Feeds this value into the given Hasher. Read more
1.3.0 · source§

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

Feeds a slice of this type into the given Hasher. Read more
source§

impl PartialEq<TaskRef> for TaskRef

source§

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

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

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
source§

impl Eq for TaskRef

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for Twhere T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for Twhere T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for Twhere T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
§

impl<T> CallHasher for Twhere T: Hash + ?Sized,

§

default fn get_hash<H, B>(value: &H, build_hasher: &B) -> u64where H: Hash + ?Sized, B: BuildHasher,

source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for Twhere U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> ToOwned for Twhere T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for Twhere U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.