1// SPDX-License-Identifier: GPL-2.0
  2
  3//! Tasks (threads and processes).
  4//!
  5//! C header: [`include/linux/sched.h`](srctree/include/linux/sched.h).
  6
  7use crate::{bindings, types::Opaque};
  8use core::{marker::PhantomData, ops::Deref, ptr};
  9
 10/// Returns the currently running task.
 11#[macro_export]
 12macro_rules! current {
 13    () => {
 14        // SAFETY: Deref + addr-of below create a temporary `TaskRef` that cannot outlive the
 15        // caller.
 16        unsafe { &*$crate::task::Task::current() }
 17    };
 18}
 19
 20/// Wraps the kernel's `struct task_struct`.
 21///
 22/// # Invariants
 23///
 24/// All instances are valid tasks created by the C portion of the kernel.
 25///
 26/// Instances of this type are always ref-counted, that is, a call to `get_task_struct` ensures
 27/// that the allocation remains valid at least until the matching call to `put_task_struct`.
 28///
 29/// # Examples
 30///
 31/// The following is an example of getting the PID of the current thread with zero additional cost
 32/// when compared to the C version:
 33///
 34/// ```
 35/// let pid = current!().pid();
 36/// ```
 37///
 38/// Getting the PID of the current process, also zero additional cost:
 39///
 40/// ```
 41/// let pid = current!().group_leader().pid();
 42/// ```
 43///
 44/// Getting the current task and storing it in some struct. The reference count is automatically
 45/// incremented when creating `State` and decremented when it is dropped:
 46///
 47/// ```
 48/// use kernel::{task::Task, types::ARef};
 49///
 50/// struct State {
 51///     creator: ARef<Task>,
 52///     index: u32,
 53/// }
 54///
 55/// impl State {
 56///     fn new() -> Self {
 57///         Self {
 58///             creator: current!().into(),
 59///             index: 0,
 60///         }
 61///     }
 62/// }
 63/// ```
 64#[repr(transparent)]
 65pub struct Task(pub(crate) Opaque<bindings::task_struct>);
 66
 67// SAFETY: By design, the only way to access a `Task` is via the `current` function or via an
 68// `ARef<Task>` obtained through the `AlwaysRefCounted` impl. This means that the only situation in
 69// which a `Task` can be accessed mutably is when the refcount drops to zero and the destructor
 70// runs. It is safe for that to happen on any thread, so it is ok for this type to be `Send`.
 71unsafe impl Send for Task {}
 72
 73// SAFETY: It's OK to access `Task` through shared references from other threads because we're
 74// either accessing properties that don't change (e.g., `pid`, `group_leader`) or that are properly
 75// synchronised by C code (e.g., `signal_pending`).
 76unsafe impl Sync for Task {}
 77
 78/// The type of process identifiers (PIDs).
 79type Pid = bindings::pid_t;
 80
 81impl Task {
 82    /// Returns a task reference for the currently executing task/thread.
 83    ///
 84    /// The recommended way to get the current task/thread is to use the
 85    /// [`current`] macro because it is safe.
 86    ///
 87    /// # Safety
 88    ///
 89    /// Callers must ensure that the returned object doesn't outlive the current task/thread.
 90    pub unsafe fn current() -> impl Deref<Target = Task> {
 91        struct TaskRef<'a> {
 92            task: &'a Task,
 93            _not_send: PhantomData<*mut ()>,
 94        }
 95
 96        impl Deref for TaskRef<'_> {
 97            type Target = Task;
 98
 99            fn deref(&self) -> &Self::Target {
100                self.task
101            }
102        }
103
104        // SAFETY: Just an FFI call with no additional safety requirements.
105        let ptr = unsafe { bindings::get_current() };
106
107        TaskRef {
108            // SAFETY: If the current thread is still running, the current task is valid. Given
109            // that `TaskRef` is not `Send`, we know it cannot be transferred to another thread
110            // (where it could potentially outlive the caller).
111            task: unsafe { &*ptr.cast() },
112            _not_send: PhantomData,
113        }
114    }
115
116    /// Returns the group leader of the given task.
117    pub fn group_leader(&self) -> &Task {
118        // SAFETY: By the type invariant, we know that `self.0` is a valid task. Valid tasks always
119        // have a valid group_leader.
120        let ptr = unsafe { *ptr::addr_of!((*self.0.get()).group_leader) };
121
122        // SAFETY: The lifetime of the returned task reference is tied to the lifetime of `self`,
123        // and given that a task has a reference to its group leader, we know it must be valid for
124        // the lifetime of the returned task reference.
125        unsafe { &*ptr.cast() }
126    }
127
128    /// Returns the PID of the given task.
129    pub fn pid(&self) -> Pid {
130        // SAFETY: By the type invariant, we know that `self.0` is a valid task. Valid tasks always
131        // have a valid pid.
132        unsafe { *ptr::addr_of!((*self.0.get()).pid) }
133    }
134
135    /// Determines whether the given task has pending signals.
136    pub fn signal_pending(&self) -> bool {
137        // SAFETY: By the type invariant, we know that `self.0` is valid.
138        unsafe { bindings::signal_pending(self.0.get()) != 0 }
139    }
140
141    /// Wakes up the task.
142    pub fn wake_up(&self) {
143        // SAFETY: By the type invariant, we know that `self.0.get()` is non-null and valid.
144        // And `wake_up_process` is safe to be called for any valid task, even if the task is
145        // running.
146        unsafe { bindings::wake_up_process(self.0.get()) };
147    }
148}
149
150// SAFETY: The type invariants guarantee that `Task` is always ref-counted.
151unsafe impl crate::types::AlwaysRefCounted for Task {
152    fn inc_ref(&self) {
153        // SAFETY: The existence of a shared reference means that the refcount is nonzero.
154        unsafe { bindings::get_task_struct(self.0.get()) };
155    }
156
157    unsafe fn dec_ref(obj: ptr::NonNull<Self>) {
158        // SAFETY: The safety requirements guarantee that the refcount is nonzero.
159        unsafe { bindings::put_task_struct(obj.cast().as_ptr()) }
160    }
161}