1 // SPDX-License-Identifier: GPL-2.0 2 3 //! Tasks (threads and processes). 4 //! 5 //! C header: [`include/linux/sched.h`](../../../../include/linux/sched.h). 6 7 use crate::{bindings, types::Opaque}; 8 use core::{marker::PhantomData, ops::Deref, ptr}; 9 10 /// Returns the currently running task. 11 #[macro_export] 12 macro_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)] 65 pub struct Task(pub(crate) Opaque<bindings::task_struct>); 66 67 // SAFETY: It's OK to access `Task` through references from other threads because we're either 68 // accessing properties that don't change (e.g., `pid`, `group_leader`) or that are properly 69 // synchronised by C code (e.g., `signal_pending`). 70 unsafe impl Sync for Task {} 71 72 /// The type of process identifiers (PIDs). 73 type Pid = bindings::pid_t; 74 75 impl Task { 76 /// Returns a task reference for the currently executing task/thread. 77 /// 78 /// The recommended way to get the current task/thread is to use the 79 /// [`current`](crate::current) macro because it is safe. 80 /// 81 /// # Safety 82 /// 83 /// Callers must ensure that the returned object doesn't outlive the current task/thread. 84 pub unsafe fn current() -> impl Deref<Target = Task> { 85 struct TaskRef<'a> { 86 task: &'a Task, 87 _not_send: PhantomData<*mut ()>, 88 } 89 90 impl Deref for TaskRef<'_> { 91 type Target = Task; 92 93 fn deref(&self) -> &Self::Target { 94 self.task 95 } 96 } 97 98 // SAFETY: Just an FFI call with no additional safety requirements. 99 let ptr = unsafe { bindings::get_current() }; 100 101 TaskRef { 102 // SAFETY: If the current thread is still running, the current task is valid. Given 103 // that `TaskRef` is not `Send`, we know it cannot be transferred to another thread 104 // (where it could potentially outlive the caller). 105 task: unsafe { &*ptr.cast() }, 106 _not_send: PhantomData, 107 } 108 } 109 110 /// Returns the group leader of the given task. 111 pub fn group_leader(&self) -> &Task { 112 // SAFETY: By the type invariant, we know that `self.0` is a valid task. Valid tasks always 113 // have a valid group_leader. 114 let ptr = unsafe { *ptr::addr_of!((*self.0.get()).group_leader) }; 115 116 // SAFETY: The lifetime of the returned task reference is tied to the lifetime of `self`, 117 // and given that a task has a reference to its group leader, we know it must be valid for 118 // the lifetime of the returned task reference. 119 unsafe { &*ptr.cast() } 120 } 121 122 /// Returns the PID of the given task. 123 pub fn pid(&self) -> Pid { 124 // SAFETY: By the type invariant, we know that `self.0` is a valid task. Valid tasks always 125 // have a valid pid. 126 unsafe { *ptr::addr_of!((*self.0.get()).pid) } 127 } 128 129 /// Determines whether the given task has pending signals. 130 pub fn signal_pending(&self) -> bool { 131 // SAFETY: By the type invariant, we know that `self.0` is valid. 132 unsafe { bindings::signal_pending(self.0.get()) != 0 } 133 } 134 135 /// Wakes up the task. 136 pub fn wake_up(&self) { 137 // SAFETY: By the type invariant, we know that `self.0.get()` is non-null and valid. 138 // And `wake_up_process` is safe to be called for any valid task, even if the task is 139 // running. 140 unsafe { bindings::wake_up_process(self.0.get()) }; 141 } 142 } 143 144 // SAFETY: The type invariants guarantee that `Task` is always ref-counted. 145 unsafe impl crate::types::AlwaysRefCounted for Task { 146 fn inc_ref(&self) { 147 // SAFETY: The existence of a shared reference means that the refcount is nonzero. 148 unsafe { bindings::get_task_struct(self.0.get()) }; 149 } 150 151 unsafe fn dec_ref(obj: ptr::NonNull<Self>) { 152 // SAFETY: The safety requirements guarantee that the refcount is nonzero. 153 unsafe { bindings::put_task_struct(obj.cast().as_ptr()) } 154 } 155 } 156