Refactor Task into task_struct and TaskRef+friends into task (theseus-os#856)

Refactor the large `task` crate into two crates:
1. `task_struct`: the basic `Task` type that contains only
   core states related to a task, e.g., task ID, name, runstate,
   saved register context, TLS data area, etc.
2. `task`: the higher-level `TaskRef` type, a shareable reference
   to a `Task`, and its derivatives like `JoinableTaskRef`.
   This crate also includes the system task list, kill handlers,
   task switching functions, and current task getters.

Why? Upcoming changes like theseus-os#774, theseus-os#809, theseus-os#820, and theseus-os#821
necessitate some refactoring to avoid cyclic dependencies
between `task`, `scheduler`, `runqueue*`, etc.

* The joinability of a task is moved from `Task` into
  `TaskRef`, since a task doesn't care about joinability until
  it is made into a `TaskRef`, which is actually usable
  and schedulable. Similarly, only a `TaskRef` can be added
  to the system task list, not a bare `Task`.

* We expose access to private `Task` fields via a new type
  `ExposedTask`, which only the `task` crate can instantiate
  in a useful way.

* Add a new `WeakTaskRef` type that is a weak reference
  to a `TaskRef`, and use this for anything related to
  debugging or printing task info, e.g., in `task_fs`, `ps`, etc.

* Make the global system task list private and expose
  access to it via the new `WeakTaskRef` type.
  This prevents callers from holding the lock around
  the system task list, which would prevent others from
  spawning new tasks or cleaning up exited tasks.

* Reduce the `Task` constructor to a single method
  that accepts a new `InheritedStates` enum, allowing the
  initial contextual states for a new task to come from
  either an existing task or a custom set of states.
  These states include the task's `Environment`, namespace,
  memory mgmt info, and application crate reference.
  * The `FailureCleanupFunction` is now passed into the
    `TaskRef` constructor rather than the `Task` constructor,
    as its signature includes a `TaskRef`-based type. 6ef4e11

Author: tsoutsman

book/print.html

@@ -1180,7 +1180,7 @@ <h3 id="the-taskref-type"><a class="header" href="#the-taskref-type">The <code>T
 </blockquote>
 <h3 id="the-global-task-list"><a class="header" href="#the-global-task-list">The global task list</a></h3>
 <p>Like all other OSes, Theseus maintains a global list of all tasks in the system.
-Currently, this <a href="https://theseus-os.github.io/Theseus/doc/task/struct.TASKLIST.html"><code>TASKLIST</code></a> is stored as a map from a numeric task ID to a <code>TaskRef</code>.</p>
+Currently, this task list is stored as a map from a numeric task ID to a <code>TaskRef</code>.</p>
 <p>Tasks are added to the task list when they are initially spawned, and will remain in the task list for the entirety of their lifecycle.
 It is important to note that the presence of a task in the task list is not indicative of that task's runnability or execution status.
 A task is only removed from the task list once it has been <em>reaped</em>, i.e., it has completely exited and its exit value has been &quot;taken&quot; by another task; for example, a &quot;parent&quot; task may reap a &quot;child&quot; task that it has spawned.</p>

book/searchindex.js

@@ -234,7 +234,7 @@ <h3 id="the-taskref-type"><a class="header" href="#the-taskref-type">The <code>T
 </blockquote>
 <h3 id="the-global-task-list"><a class="header" href="#the-global-task-list">The global task list</a></h3>
 <p>Like all other OSes, Theseus maintains a global list of all tasks in the system.
-Currently, this <a href="https://theseus-os.github.io/Theseus/doc/task/struct.TASKLIST.html"><code>TASKLIST</code></a> is stored as a map from a numeric task ID to a <code>TaskRef</code>.</p>
+Currently, this task list is stored as a map from a numeric task ID to a <code>TaskRef</code>.</p>
 <p>Tasks are added to the task list when they are initially spawned, and will remain in the task list for the entirety of their lifecycle.
 It is important to note that the presence of a task in the task list is not indicative of that task's runnability or execution status.
 A task is only removed from the task list once it has been <em>reaped</em>, i.e., it has completely exited and its exit value has been &quot;taken&quot; by another task; for example, a &quot;parent&quot; task may reap a &quot;child&quot; task that it has spawned.</p>

book/searchindex.json

@@ -1,3 +1,3 @@
-<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="generator" content="rustdoc"><meta name="description" content="Entry to rust for an AP. The arguments must match the invocation order in “ap_boot.asm”"><meta name="keywords" content="rust, rustlang, rust-lang, kstart_ap"><title>kstart_ap in ap_start - Rust</title><link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/SourceSerif4-Regular-1f7d512b176f0f72.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/FiraSans-Regular-018c141bf0843ffd.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/FiraSans-Medium-8f9a781e4970d388.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/SourceCodePro-Regular-562dcc5011b6de7d.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/SourceSerif4-Bold-124a1ca42af929b6.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/SourceCodePro-Semibold-d899c5a5c4aeb14a.ttf.woff2"><link rel="stylesheet" href="../static.files/normalize-76eba96aa4d2e634.css"><link rel="stylesheet" href="../static.files/rustdoc-fbcde169c4acde5f.css" id="mainThemeStyle"><link rel="stylesheet" id="themeStyle" href="../static.files/light-4743e13df3dfe8c4.css"><link rel="stylesheet" disabled href="../static.files/dark-0e1b889528bd466b.css"><link rel="stylesheet" disabled href="../static.files/ayu-65289d5d067c7c66.css"><script id="default-settings" ></script><script src="../static.files/storage-d43fa987303ecbbb.js"></script><script defer src="sidebar-items.js"></script><script defer src="../static.files/main-bc1b32400f872ddb.js"></script><noscript><link rel="stylesheet" href="../static.files/noscript-13285aec31fa243e.css"></noscript><link rel="alternate icon" type="image/png" href="../static.files/favicon-16x16-8b506e7a72182f1c.png"><link rel="alternate icon" type="image/png" href="../static.files/favicon-32x32-422f7d1d52889060.png"><link rel="icon" type="image/svg+xml" href="../static.files/favicon-2c020d218678b618.svg"></head><body class="rustdoc fn"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><nav class="mobile-topbar"><button class="sidebar-menu-toggle">&#9776;</button><a class="logo-container" href="../ap_start/index.html"><img class="rust-logo" src="../static.files/rust-logo-151179464ae7ed46.svg" alt="logo"></a><h2></h2></nav><nav class="sidebar"><a class="logo-container" href="../ap_start/index.html"><img class="rust-logo" src="../static.files/rust-logo-151179464ae7ed46.svg" alt="logo"></a><div class="sidebar-elems"><h2><a href="index.html">In ap_start</a></h2></div></nav><main><div class="width-limiter"><nav class="sub"><form class="search-form"><span></span><input class="search-input" name="search" aria-label="Run search in the documentation" autocomplete="off" spellcheck="false" placeholder="Click or press ‘S’ to search, ‘?’ for more options…" type="search"><div id="help-button" title="help" tabindex="-1"><a href="../help.html">?</a></div><div id="settings-menu" tabindex="-1"><a href="../settings.html" title="settings"><img width="22" height="22" alt="Change settings" src="../static.files/wheel-5ec35bf9ca753509.svg"></a></div></form></nav><section id="main-content" class="content"><div class="main-heading"><h1 class="fqn">Function <a href="index.html">ap_start</a>::<wbr><a class="fn" href="#">kstart_ap</a><button id="copy-path" onclick="copy_path(this)" title="Copy item path to clipboard"><img src="../static.files/clipboard-7571035ce49a181d.svg" width="19" height="18" alt="Copy item path"></button></h1><span class="out-of-band"><a class="srclink" href="../src/ap_start/lib.rs.html#45-117">source</a> · <button id="toggle-all-docs" title="collapse all docs">[<span>&#x2212;</span>]</button></span></div><div class="item-decl"><pre class="rust fn"><code>pub fn kstart_ap(<br>&nbsp;&nbsp;&nbsp;&nbsp;processor_id: <a class="primitive" href="https://doc.rust-lang.org/nightly/core/primitive.u8.html">u8</a>,<br>&nbsp;&nbsp;&nbsp;&nbsp;apic_id: <a class="primitive" href="https://doc.rust-lang.org/nightly/core/primitive.u8.html">u8</a>,<br>&nbsp;&nbsp;&nbsp;&nbsp;_stack_start: VirtualAddress,<br>&nbsp;&nbsp;&nbsp;&nbsp;_stack_end: VirtualAddress,<br>&nbsp;&nbsp;&nbsp;&nbsp;nmi_lint: <a class="primitive" href="https://doc.rust-lang.org/nightly/core/primitive.u8.html">u8</a>,<br>&nbsp;&nbsp;&nbsp;&nbsp;nmi_flags: <a class="primitive" href="https://doc.rust-lang.org/nightly/core/primitive.u16.html">u16</a><br>) -&gt; <a class="primitive" href="https://doc.rust-lang.org/nightly/core/primitive.never.html">!</a></code></pre></div><details class="rustdoc-toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><p>Entry to rust for an AP.
+<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="generator" content="rustdoc"><meta name="description" content="Entry to rust for an AP. The arguments must match the invocation order in “ap_boot.asm”"><meta name="keywords" content="rust, rustlang, rust-lang, kstart_ap"><title>kstart_ap in ap_start - Rust</title><link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/SourceSerif4-Regular-1f7d512b176f0f72.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/FiraSans-Regular-018c141bf0843ffd.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/FiraSans-Medium-8f9a781e4970d388.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/SourceCodePro-Regular-562dcc5011b6de7d.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/SourceSerif4-Bold-124a1ca42af929b6.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/SourceCodePro-Semibold-d899c5a5c4aeb14a.ttf.woff2"><link rel="stylesheet" href="../static.files/normalize-76eba96aa4d2e634.css"><link rel="stylesheet" href="../static.files/rustdoc-fbcde169c4acde5f.css" id="mainThemeStyle"><link rel="stylesheet" id="themeStyle" href="../static.files/light-4743e13df3dfe8c4.css"><link rel="stylesheet" disabled href="../static.files/dark-0e1b889528bd466b.css"><link rel="stylesheet" disabled href="../static.files/ayu-65289d5d067c7c66.css"><script id="default-settings" ></script><script src="../static.files/storage-d43fa987303ecbbb.js"></script><script defer src="sidebar-items.js"></script><script defer src="../static.files/main-bc1b32400f872ddb.js"></script><noscript><link rel="stylesheet" href="../static.files/noscript-13285aec31fa243e.css"></noscript><link rel="alternate icon" type="image/png" href="../static.files/favicon-16x16-8b506e7a72182f1c.png"><link rel="alternate icon" type="image/png" href="../static.files/favicon-32x32-422f7d1d52889060.png"><link rel="icon" type="image/svg+xml" href="../static.files/favicon-2c020d218678b618.svg"></head><body class="rustdoc fn"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><nav class="mobile-topbar"><button class="sidebar-menu-toggle">&#9776;</button><a class="logo-container" href="../ap_start/index.html"><img class="rust-logo" src="../static.files/rust-logo-151179464ae7ed46.svg" alt="logo"></a><h2></h2></nav><nav class="sidebar"><a class="logo-container" href="../ap_start/index.html"><img class="rust-logo" src="../static.files/rust-logo-151179464ae7ed46.svg" alt="logo"></a><div class="sidebar-elems"><h2><a href="index.html">In ap_start</a></h2></div></nav><main><div class="width-limiter"><nav class="sub"><form class="search-form"><span></span><input class="search-input" name="search" aria-label="Run search in the documentation" autocomplete="off" spellcheck="false" placeholder="Click or press ‘S’ to search, ‘?’ for more options…" type="search"><div id="help-button" title="help" tabindex="-1"><a href="../help.html">?</a></div><div id="settings-menu" tabindex="-1"><a href="../settings.html" title="settings"><img width="22" height="22" alt="Change settings" src="../static.files/wheel-5ec35bf9ca753509.svg"></a></div></form></nav><section id="main-content" class="content"><div class="main-heading"><h1 class="fqn">Function <a href="index.html">ap_start</a>::<wbr><a class="fn" href="#">kstart_ap</a><button id="copy-path" onclick="copy_path(this)" title="Copy item path to clipboard"><img src="../static.files/clipboard-7571035ce49a181d.svg" width="19" height="18" alt="Copy item path"></button></h1><span class="out-of-band"><a class="srclink" href="../src/ap_start/lib.rs.html#45-121">source</a> · <button id="toggle-all-docs" title="collapse all docs">[<span>&#x2212;</span>]</button></span></div><div class="item-decl"><pre class="rust fn"><code>pub fn kstart_ap(<br>&nbsp;&nbsp;&nbsp;&nbsp;processor_id: <a class="primitive" href="https://doc.rust-lang.org/nightly/core/primitive.u8.html">u8</a>,<br>&nbsp;&nbsp;&nbsp;&nbsp;apic_id: <a class="primitive" href="https://doc.rust-lang.org/nightly/core/primitive.u8.html">u8</a>,<br>&nbsp;&nbsp;&nbsp;&nbsp;_stack_start: VirtualAddress,<br>&nbsp;&nbsp;&nbsp;&nbsp;_stack_end: VirtualAddress,<br>&nbsp;&nbsp;&nbsp;&nbsp;nmi_lint: <a class="primitive" href="https://doc.rust-lang.org/nightly/core/primitive.u8.html">u8</a>,<br>&nbsp;&nbsp;&nbsp;&nbsp;nmi_flags: <a class="primitive" href="https://doc.rust-lang.org/nightly/core/primitive.u16.html">u16</a><br>) -&gt; <a class="primitive" href="https://doc.rust-lang.org/nightly/core/primitive.never.html">!</a></code></pre></div><details class="rustdoc-toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><p>Entry to rust for an AP.
 The arguments must match the invocation order in “ap_boot.asm”</p>
 </div></details></section></div></main><div id="rustdoc-vars" data-root-path="../" data-static-root-path="../static.files/" data-current-crate="ap_start" data-themes="" data-resource-suffix="" data-rustdoc-version="1.68.0-nightly (0442fbabe 2023-01-10)" data-search-js="search-181581080540673f.js" data-settings-js="settings-bebeae96e00e4617.js" data-settings-css="settings-58836c674e2f7bd2.css" ></div></body></html>