blob: 43164e62d2256cb9bb4d02422e331878d412cd5e [file]
// Copyright 2026 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use crate::task::{TaskStateCode, Waiter, WaiterRef};
use starnix_sync::InterruptibleEvent;
use std::ptr::NonNull;
/// A non-owning reference to an [`InterruptibleEvent`] registered in [`RunState::Event`].
///
/// # Safety Invariant
/// An `EventRef` is only stored in `TaskMutableState::run_state` by
/// `CurrentTask::run_in_state_internal` for the lexical duration of the blocking callback (while
/// the `InterruptibleEvent` is borrowed), and is cleared back to `RunState::Running` under
/// `Task::write()` before `run_in_state_internal` returns. `RunState::wake` is only called under
/// `Task::read()`, so the pointee is guaranteed to remain valid for every `wake` call.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct EventRef(NonNull<InterruptibleEvent>);
// SAFETY: `EventRef` only provides shared (`&InterruptibleEvent`) access to the pointee, and
// `InterruptibleEvent` is `Sync`.
unsafe impl Send for EventRef {}
// SAFETY: `EventRef` only provides shared (`&InterruptibleEvent`) access to the pointee, and
// `InterruptibleEvent` is `Sync`.
unsafe impl Sync for EventRef {}
impl EventRef {
/// Creates an [`EventRef`] pointing to `event`.
///
/// # Safety
/// The caller must ensure that `event` remains valid for as long as the resulting
/// `RunState::Event` is installed in `TaskMutableState::run_state` and across all concurrent
/// `RunState::wake` calls (by clearing `run_state` back to `RunState::Running` under
/// `Task::write()` before `event`'s borrow ends).
pub(super) unsafe fn new(event: &InterruptibleEvent) -> Self {
Self(NonNull::from(event))
}
unsafe fn interrupt(&self) {
// SAFETY: By the `EventRef` invariant and `RunState::wake` safety requirement, `self.0`
// points to a live `InterruptibleEvent`.
unsafe { self.0.as_ref().interrupt() };
}
}
/// Whether, and how, this task is blocked. This enum can be extended with new
/// variants to optimize different kinds of waiting.
#[derive(Debug, Clone, PartialEq)]
pub enum RunState {
/// This task is not blocked.
///
/// The task might be running in userspace or kernel.
Running,
/// This thread is blocked in a `Waiter`.
Waiter(WaiterRef),
/// This thread is blocked in a killable `Waiter` (e.g. `wait_for_execve` during `vfork`).
///
/// Only fatal signals or process termination interrupt this wait; non-fatal signals leave it
/// blocked.
KillableWaiter(WaiterRef),
/// This thread is blocked in an `InterruptibleEvent`.
Event(EventRef),
/// This thread is frozen by a `Waiter`.
///
/// When waiting on the `Waiter`, it should have a loop to prevent any signals except
/// notification.
Frozen(Waiter),
/// This thread is stopped by a tracer (or stopped by job control).
///
/// It is not interruptible except by the tracer or SIGCONT, and can be aborted by SIGKILL.
TracingStopped,
}
impl Default for RunState {
fn default() -> Self {
RunState::Running
}
}
impl RunState {
/// Whether this task is blocked.
///
/// If the task is blocked, you can break the task out of the wait using the `wake` function.
pub fn is_blocked(&self) -> bool {
match self {
RunState::Running => false,
RunState::Waiter(waiter) | RunState::KillableWaiter(waiter) => waiter.is_valid(),
RunState::Event(_) | RunState::Frozen(_) | RunState::TracingStopped => true,
}
}
/// Whether this task is in a killable wait (e.g. `RunState::KillableWaiter`).
pub fn is_killable(&self) -> bool {
matches!(self, RunState::KillableWaiter(_))
}
/// Whether this task ignores signals other than SIGKILL while blocked in this state.
pub fn ignores_signals(&self) -> bool {
match self {
RunState::Frozen(_) | RunState::TracingStopped => true,
RunState::Running
| RunState::Waiter(_)
| RunState::KillableWaiter(_)
| RunState::Event(_) => false,
}
}
/// Unblock the task by interrupting whatever wait the task is blocked upon.
///
/// # Safety
/// If `self` is `RunState::Event`, the caller must guarantee that the target task has not yet
/// cleared its `run_state` in `CurrentTask::run_in_state_internal` (for example, by holding
/// the task's state lock while reading `run_state` and calling `wake`).
pub(super) unsafe fn wake(&self) {
match self {
RunState::Running => (),
RunState::Waiter(waiter) | RunState::KillableWaiter(waiter) => waiter.interrupt(),
// SAFETY: Guaranteed by the caller.
RunState::Event(event) => unsafe { event.interrupt() },
// When frozen or stopped, the task is immune to any interrupts.
RunState::Frozen(_) | RunState::TracingStopped => (),
}
}
/// The TaskStateCode corresponding to the RunState.
pub fn state_code(&self) -> TaskStateCode {
match self {
RunState::Running => TaskStateCode::Running,
RunState::Waiter(waiter) | RunState::KillableWaiter(waiter) => {
if waiter.is_valid() {
TaskStateCode::Sleeping
} else {
TaskStateCode::Running
}
}
RunState::Event(_) | RunState::Frozen(_) => TaskStateCode::Sleeping,
// TODO(https://fxbug.dev/566829060): Job-control stops currently report
// `TaskStateCode::TracingStop` ('t'). Distinguish them to report
// `TaskStateCode::Stopped` ('T').
RunState::TracingStopped => TaskStateCode::TracingStop,
}
}
}