Struct task::Task

source ·
pub struct Task {
    pub id: usize,
    pub name: String,
    pub mmi: MmiRef,
    pub is_an_idle_task: bool,
    pub app_crate: Option<Arc<AppCrateRef>>,
    pub namespace: Arc<CrateNamespace>,
    pub failure_cleanup_function: FailureCleanupFunction,
    /* private fields */
}
Expand description

A structure that contains contextual information for a thread of execution.

Implementation note

Only fields that do not permit interior mutability can safely be exposed as public because we allow foreign crates to directly access task struct fields.

Fields§

§id: usize

The unique identifier of this Task.

§name: String

The simple name of this Task.

§mmi: MmiRef

Memory management details: page tables, mappings, allocators, etc. This is shared among all other tasks in the same address space.

§is_an_idle_task: bool

Whether this Task is an idle task, the task that runs by default when no other task is running. There exists one idle task per core, so this is false for most tasks.

§app_crate: Option<Arc<AppCrateRef>>

For application Tasks, this is effectively a reference to the [mod_mgmt::LoadedCrate] that contains the entry function for this Task.

§namespace: Arc<CrateNamespace>

This Task is linked into and runs within the context of this [CrateNamespace].

§failure_cleanup_function: FailureCleanupFunction

The function that should be run as a last-ditch attempt to recover from this task’s failure, e.g., this can be called when unwinding itself fails. Typically, it will point to this Task’s specific instance of spawn::task_cleanup_failure(), which has generic type parameters that describe its function signature, argument type, and return type.

Implementations§

Creates a new Task structure and initializes it to be non-Runnable.

By default, the new Task will inherit some of its states from the given parent_task: its Environment, MemoryManagementInfo, CrateNamespace, and app_crate reference. If necessary, those states can be changed by setting them for the returned Task.

Arguments
  • kstack: the optional kernel Stack for this Task to use.
    • If None, a kernel stack of the default size will be allocated and used.
  • parent_task: the optional TaskRef that acts as a sort of “parent” template for this new Task. Theseus doesn’t have a true parent-child relationship between tasks; the new Task merely inherits certain states from this parent_task.
    • If None, the current task is used to determine the initial values of those states. This means that the tasking infrastructure must have been initialized before this function can be invoked with a parent_task value of None.
  • failure_cleanup_function: an error handling function that acts as a last resort when all else fails, e.g., if unwinding crashes.
Note
  • If invoking this function with a parent_task value of None, tasking must have already been initialized so the current task can be obtained.
  • This does not run the task, schedule it in, or switch to it.
  • If you want to create a new task, you should use the spawn crate instead.

Sets the Environment of this Task.

Locking / Deadlock

Obtains the lock on this Task’s inner state in order to mutate it.

Gets a reference to this task’s Environment.

Locking / Deadlock

Obtains the lock on this Task’s inner state in order to access it.

Returns true if this Task is currently running.

Returns the APIC ID of the CPU this Task is currently running on.

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

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

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

Returns the current RunState of this Task.

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.

Returns the namespace in which this Task is loaded/linked into and runs within.

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.

Returns a mutable reference to this Task’s inner state.

Note about mutability

This function requires the caller to have a mutable reference to this Task in order to protect the inner state from foreign crates accessing it through a TaskRef auto-dereferencing into a Task. This is because you can only obtain a mutable reference to a Task before you enclose it in a TaskRef wrapper type.

Locking / Deadlock

Because this function requires a mutable reference to this Task, no locks must be obtained.

Exposes read-only access to this Task’s RestartInfo by invoking the given func with a reference to its 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.

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

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” who spawned it.

Returns true if this is a userspace Task. Currently userspace support is disabled, so this always returns false.

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.

Blocks this Task by setting its runstate to RunState::Blocked.

Returns the previous runstate on success, and the current runstate on error. Will only suceed if the task is runnable or already blocked.

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.

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.

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.

Suspends this Task.

Unsuspends this Task.

Returns true if this Task is suspended.

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

Sets the waker to be awoken when this task exits.

Trait Implementations§

Formats the value using the given formatter. Read more
Formats the value using the given formatter. Read more
Executes the destructor for this type. Read more
Feeds this value into the given Hasher. Read more
Feeds a slice of this type into the given Hasher. Read more

Auto Trait Implementations§

Blanket Implementations§

Gets the TypeId of self. Read more
Immutably borrows from an owned value. Read more
Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

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

Converts the given value to a String. Read more
The type returned in the event of a conversion error.
Performs the conversion.
The type returned in the event of a conversion error.
Performs the conversion.