doc(kernel): use the definite article when referring to a specific task state

Author: yvt

src/constance/src/kernel.rs

@@ -85,7 +85,7 @@ pub trait Kernel: Port + KernelCfg2 + Sized + 'static {
     /// [Priority Boost]: crate#system-states
     fn is_priority_boost_active() -> bool;
 
-    /// Terminate the current task, putting it into a Dormant state.
+    /// Terminate the current task, putting it into the Dormant state.
     ///
     /// The kernel (to be precise, the port) makes an implicit call to this
     /// function when a task entry point function returns.
@@ -100,9 +100,9 @@ pub trait Kernel: Port + KernelCfg2 + Sized + 'static {
     ///
     unsafe fn exit_task() -> Result<!, ExitTaskError>;
 
-    /// Put the current task into a Waiting state until the task's token is made
-    /// available by [`Task::unpark`]. The token is initially absent when the
-    /// task is activated.
+    /// Put the current task into the Waiting state until the task's token is
+    /// made available by [`Task::unpark`]. The token is initially absent when
+    /// the task is activated.
     ///
     /// The token will be consumed when this method returns successfully.
     ///

src/constance/src/kernel/error.rs

@@ -158,7 +158,7 @@ define_error! {
         BadId,
         /// CPU Lock is active.
         BadContext,
-        /// The task is already active (not in a Dormant state).
+        /// The task is already active (not in the Dormant state).
         ///
         /// This error code originates from `E_QOVR` defined in the μITRON 4.0
         /// specification. In this specification, the `act_tsk` (activate task)
@@ -190,7 +190,7 @@ define_error! {
         BadId,
         /// CPU Lock is active.
         BadContext,
-        /// The task is not in a Waiting state.
+        /// The task is not in the Waiting state.
         BadObjectState,
     }
 }
@@ -261,7 +261,7 @@ define_error! {
         BadContext,
         /// The task ID is out of range.
         BadId,
-        /// The task is in a Dormant state.
+        /// The task is in the Dormant state.
         BadObjectState,
     }
 }
@@ -277,7 +277,7 @@ define_error! {
         BadId,
         /// The task already has a token.
         QueueOverflow,
-        /// The task is in a Dormant state.
+        /// The task is in the Dormant state.
         BadObjectState,
     }
 }

src/constance/src/kernel/task.rs

@@ -20,6 +20,16 @@ use crate::utils::{
 ///
 /// > **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**
+///  - **Ready**
+///  - **Running**
+///  - **Waiting**
+///
 #[doc(include = "../common.md")]
 #[repr(transparent)]
 pub struct Task<System>(Id, PhantomData<System>);
@@ -82,7 +92,7 @@ impl<System: Kernel> Task<System> {
     /// Get the current task.
     ///
     /// In a task context, this method returns the currently running task. In an
-    /// interrupt handler, this method returns the interrupted task (if any).
+    /// interrupt context, this method returns the interrupted task (if any).
     pub fn current() -> Result<Option<Self>, GetCurrentTaskError> {
         let _lock = utils::lock_cpu::<System>()?;
         let task_cb = if let Some(cb) = System::state().running_task() {
@@ -391,7 +401,7 @@ pub(super) fn init_task<System: Kernel>(
         // `PendingActivation` is equivalent to `Dormant` but serves as a marker
         // indicating tasks that should be activated by `init_task`.
 
-        // Safety: CPU Lock active, the task is (essentially) in a Dormant state
+        // Safety: CPU Lock active, the task is (essentially) in the Dormant state
         unsafe { System::initialize_task_state(task_cb) };
 
         // Safety: The previous state is PendingActivation (which is equivalent
@@ -447,7 +457,7 @@ fn activate<System: Kernel>(
     // Discard a park token if the task has one
     task_cb.park_token.replace(&mut *lock, false);
 
-    // Safety: CPU Lock active, the task is in a Dormant state
+    // Safety: CPU Lock active, the task is in the Dormant state
     unsafe { System::initialize_task_state(task_cb) };
 
     // Safety: The previous state is Dormant, and we just initialized the task
@@ -486,7 +496,7 @@ pub(super) unsafe fn make_ready<System: Kernel>(
 /// Relinquish CPU Lock. After that, if there's a higher-priority task than
 /// `running_task`, call `Port::yield_cpu`.
 ///
-/// System services that transition a task into a Ready state should call
+/// System services that transition a task into the Ready state should call
 /// this before returning to the caller.
 pub(super) fn unlock_cpu_and_check_preemption<System: Kernel>(lock: utils::CpuLockGuard<System>) {
     // If Priority Boost is active, treat the currently running task as the
@@ -585,7 +595,7 @@ pub(super) fn choose_next_running_task<System: Kernel>(
         None
     };
 
-    // If `prev_running_task` is in a Running state, transition it into Ready
+    // If `prev_running_task` is in the Running state, transition it into Ready
     if let Some(running_task) = prev_running_task {
         match running_task.st.read(&*lock) {
             TaskSt::Running => {
@@ -672,7 +682,7 @@ fn unpark_exact<System: Kernel>(
     };
 
     if is_parked {
-        // Unblock the task. We confirmed that the task is in a Waiting state,
+        // Unblock the task. We confirmed that the task is in the Waiting state,
         // so `interrupt_task` should succeed.
         wait::interrupt_task(lock.borrow_mut(), task_cb, Ok(())).unwrap();
 

src/constance/src/kernel/wait.rs

@@ -156,7 +156,7 @@ pub enum QueueOrder {
 /// The wait state of a task.
 pub(crate) struct TaskWait<System: Port> {
     /// The wait object describing the ongoing Waiting state of the task. Should
-    /// be `None` iff the task is not in a Waiting state.
+    /// be `None` iff the task is not in the Waiting state.
     ///
     /// The pointee must be valid.
     current_wait: CpuLockCell<System, Option<WaitRef<System>>>,
@@ -185,7 +185,7 @@ impl<System: Port> WaitQueue<System> {
 
 impl<System: Kernel> WaitQueue<System> {
     /// Insert a wait object pertaining to the currently running task to `self`,
-    /// transitioning the task into a Waiting state.
+    /// transitioning the task into the Waiting state.
     ///
     /// The current context must be [waitable] (This function doesn't check
     /// that). The caller should use `expect_waitable_context` to do that.
@@ -463,7 +463,7 @@ fn complete_wait<System: Kernel>(
 
     // Make the task Ready
     //
-    // Safety: The task is in a Waiting state, meaning the task state is valid
+    // Safety: The task is in the Waiting state, meaning the task state is valid
     // and ready to resume from the point where it was previously interrupted.
     // A proper clean up for exiting the Waiting state is already done as well.
     unsafe { task::make_ready(lock, task_cb) };
@@ -474,7 +474,7 @@ fn complete_wait<System: Kernel>(
 /// This method may make the task Ready, but doesn't yield the processor.
 /// Call `unlock_cpu_and_check_preemption` as needed.
 ///
-/// Returns `Err(BadObjectState)` if the task is not in a Waiting state.
+/// Returns `Err(BadObjectState)` if the task is not in the Waiting state.
 pub(super) fn interrupt_task<System: Kernel>(
     mut lock: CpuLockGuardBorrowMut<'_, System>,
     task_cb: &'static TaskCb<System>,
@@ -485,7 +485,7 @@ pub(super) fn interrupt_task<System: Kernel>(
             // Interrupt the ongoing wait operation.
             let wait_ref = task_cb.wait.current_wait.get(&*lock);
 
-            // The task is in a Waiting state, so `wait_ref` must be `Some(_)`
+            // The task is in the Waiting state, so `wait_ref` must be `Some(_)`
             let wait_ref = wait_ref.unwrap();
 
             // Safety: ... and `wait_ref` must point to an existing `Wait`