aboutsummaryrefslogtreecommitdiff
path: root/src/runtime/task
diff options
context:
space:
mode:
Diffstat (limited to 'src/runtime/task')
-rw-r--r--src/runtime/task/core.rs16
-rw-r--r--src/runtime/task/error.rs4
-rw-r--r--src/runtime/task/harness.rs18
-rw-r--r--src/runtime/task/inject.rs12
-rw-r--r--src/runtime/task/list.rs10
-rw-r--r--src/runtime/task/mod.rs12
-rw-r--r--src/runtime/task/raw.rs12
-rw-r--r--src/runtime/task/state.rs36
8 files changed, 60 insertions, 60 deletions
diff --git a/src/runtime/task/core.rs b/src/runtime/task/core.rs
index 51b6496..776e834 100644
--- a/src/runtime/task/core.rs
+++ b/src/runtime/task/core.rs
@@ -44,22 +44,22 @@ pub(super) struct CoreStage<T: Future> {
///
/// Holds the future or output, depending on the stage of execution.
pub(super) struct Core<T: Future, S> {
- /// Scheduler used to drive this future
+ /// Scheduler used to drive this future.
pub(super) scheduler: S,
- /// Either the future or the output
+ /// Either the future or the output.
pub(super) stage: CoreStage<T>,
}
/// Crate public as this is also needed by the pool.
#[repr(C)]
pub(crate) struct Header {
- /// Task state
+ /// Task state.
pub(super) state: State,
pub(super) owned: UnsafeCell<linked_list::Pointers<Header>>,
- /// Pointer to next task, used with the injection queue
+ /// Pointer to next task, used with the injection queue.
pub(super) queue_next: UnsafeCell<Option<NonNull<Header>>>,
/// Table of function pointers for executing actions on the task.
@@ -133,7 +133,7 @@ impl<T: Future> CoreStage<T> {
self.stage.with_mut(f)
}
- /// Poll the future
+ /// Polls the future.
///
/// # Safety
///
@@ -169,7 +169,7 @@ impl<T: Future> CoreStage<T> {
res
}
- /// Drop the future
+ /// Drops the future.
///
/// # Safety
///
@@ -181,7 +181,7 @@ impl<T: Future> CoreStage<T> {
}
}
- /// Store the task output
+ /// Stores the task output.
///
/// # Safety
///
@@ -193,7 +193,7 @@ impl<T: Future> CoreStage<T> {
}
}
- /// Take the task output
+ /// Takes the task output.
///
/// # Safety
///
diff --git a/src/runtime/task/error.rs b/src/runtime/task/error.rs
index 17fb093..1a8129b 100644
--- a/src/runtime/task/error.rs
+++ b/src/runtime/task/error.rs
@@ -29,12 +29,12 @@ impl JoinError {
}
}
- /// Returns true if the error was caused by the task being cancelled
+ /// Returns true if the error was caused by the task being cancelled.
pub fn is_cancelled(&self) -> bool {
matches!(&self.repr, Repr::Cancelled)
}
- /// Returns true if the error was caused by the task panicking
+ /// Returns true if the error was caused by the task panicking.
///
/// # Examples
///
diff --git a/src/runtime/task/harness.rs b/src/runtime/task/harness.rs
index 41b4193..0996e52 100644
--- a/src/runtime/task/harness.rs
+++ b/src/runtime/task/harness.rs
@@ -10,7 +10,7 @@ use std::panic;
use std::ptr::NonNull;
use std::task::{Context, Poll, Waker};
-/// Typed raw task handle
+/// Typed raw task handle.
pub(super) struct Harness<T: Future, S: 'static> {
cell: NonNull<Cell<T, S>>,
}
@@ -74,7 +74,7 @@ where
}
}
- /// Poll the task and cancel it if necessary. This takes ownership of a
+ /// Polls the task and cancel it if necessary. This takes ownership of a
/// ref-count.
///
/// If the return value is Notified, the caller is given ownership of two
@@ -124,7 +124,7 @@ where
}
}
- /// Forcibly shutdown the task
+ /// Forcibly shuts down the task.
///
/// Attempt to transition to `Running` in order to forcibly shutdown the
/// task. If the task is currently running or in a state of completion, then
@@ -192,7 +192,7 @@ where
}
}
- /// Remotely abort the task.
+ /// Remotely aborts the task.
///
/// The caller should hold a ref-count, but we do not consume it.
///
@@ -280,7 +280,7 @@ where
// ====== internal ======
- /// Complete the task. This method assumes that the state is RUNNING.
+ /// Completes the task. This method assumes that the state is RUNNING.
fn complete(self) {
// The future has completed and its output has been written to the task
// stage. We transition from running to complete.
@@ -310,7 +310,7 @@ where
}
}
- /// Release the task from the scheduler. Returns the number of ref-counts
+ /// Releases the task from the scheduler. Returns the number of ref-counts
/// that should be decremented.
fn release(&self) -> usize {
// We don't actually increment the ref-count here, but the new task is
@@ -325,7 +325,7 @@ where
}
}
- /// Create a new task that holds its own ref-count.
+ /// Creates a new task that holds its own ref-count.
///
/// # Safety
///
@@ -425,7 +425,7 @@ enum PollFuture {
Dealloc,
}
-/// Cancel the task and store the appropriate error in the stage field.
+/// Cancels the task and store the appropriate error in the stage field.
fn cancel_task<T: Future>(stage: &CoreStage<T>) {
// Drop the future from a panic guard.
let res = panic::catch_unwind(panic::AssertUnwindSafe(|| {
@@ -442,7 +442,7 @@ fn cancel_task<T: Future>(stage: &CoreStage<T>) {
}
}
-/// Poll the future. If the future completes, the output is written to the
+/// Polls the future. If the future completes, the output is written to the
/// stage field.
fn poll_future<T: Future>(core: &CoreStage<T>, cx: Context<'_>) -> Poll<()> {
// Poll the future.
diff --git a/src/runtime/task/inject.rs b/src/runtime/task/inject.rs
index d1f0aee..1585e13 100644
--- a/src/runtime/task/inject.rs
+++ b/src/runtime/task/inject.rs
@@ -11,7 +11,7 @@ use std::sync::atomic::Ordering::{Acquire, Release};
/// Growable, MPMC queue used to inject new tasks into the scheduler and as an
/// overflow queue when the local, fixed-size, array queue overflows.
pub(crate) struct Inject<T: 'static> {
- /// Pointers to the head and tail of the queue
+ /// Pointers to the head and tail of the queue.
pointers: Mutex<Pointers>,
/// Number of pending tasks in the queue. This helps prevent unnecessary
@@ -22,13 +22,13 @@ pub(crate) struct Inject<T: 'static> {
}
struct Pointers {
- /// True if the queue is closed
+ /// True if the queue is closed.
is_closed: bool,
- /// Linked-list head
+ /// Linked-list head.
head: Option<NonNull<task::Header>>,
- /// Linked-list tail
+ /// Linked-list tail.
tail: Option<NonNull<task::Header>>,
}
@@ -52,7 +52,7 @@ impl<T: 'static> Inject<T> {
self.len() == 0
}
- /// Close the injection queue, returns `true` if the queue is open when the
+ /// Closes the injection queue, returns `true` if the queue is open when the
/// transition is made.
pub(crate) fn close(&self) -> bool {
let mut p = self.pointers.lock();
@@ -137,7 +137,7 @@ impl<T: 'static> Inject<T> {
self.push_batch_inner(first, prev, counter);
}
- /// Insert several tasks that have been linked together into the queue.
+ /// Inserts several tasks that have been linked together into the queue.
///
/// The provided head and tail may be be the same task. In this case, a
/// single task is inserted.
diff --git a/src/runtime/task/list.rs b/src/runtime/task/list.rs
index edd3c4f..7758f8d 100644
--- a/src/runtime/task/list.rs
+++ b/src/runtime/task/list.rs
@@ -78,7 +78,7 @@ impl<S: 'static> OwnedTasks<S> {
}
}
- /// Bind the provided task to this OwnedTasks instance. This fails if the
+ /// Binds the provided task to this OwnedTasks instance. This fails if the
/// OwnedTasks has been closed.
pub(crate) fn bind<T>(
&self,
@@ -110,7 +110,7 @@ impl<S: 'static> OwnedTasks<S> {
}
}
- /// Assert that the given task is owned by this OwnedTasks and convert it to
+ /// Asserts that the given task is owned by this OwnedTasks and convert it to
/// a LocalNotified, giving the thread permission to poll this task.
#[inline]
pub(crate) fn assert_owner(&self, task: Notified<S>) -> LocalNotified<S> {
@@ -124,7 +124,7 @@ impl<S: 'static> OwnedTasks<S> {
}
}
- /// Shut down all tasks in the collection. This call also closes the
+ /// Shuts down all tasks in the collection. This call also closes the
/// collection, preventing new items from being added.
pub(crate) fn close_and_shutdown_all(&self)
where
@@ -213,7 +213,7 @@ impl<S: 'static> LocalOwnedTasks<S> {
}
}
- /// Shut down all tasks in the collection. This call also closes the
+ /// Shuts down all tasks in the collection. This call also closes the
/// collection, preventing new items from being added.
pub(crate) fn close_and_shutdown_all(&self)
where
@@ -241,7 +241,7 @@ impl<S: 'static> LocalOwnedTasks<S> {
unsafe { inner.list.remove(task.header().into()) })
}
- /// Assert that the given task is owned by this LocalOwnedTasks and convert
+ /// Asserts that the given task is owned by this LocalOwnedTasks and convert
/// it to a LocalNotified, giving the thread permission to poll this task.
#[inline]
pub(crate) fn assert_owner(&self, task: Notified<S>) -> LocalNotified<S> {
diff --git a/src/runtime/task/mod.rs b/src/runtime/task/mod.rs
index 5f0d5ab..1f18209 100644
--- a/src/runtime/task/mod.rs
+++ b/src/runtime/task/mod.rs
@@ -173,7 +173,7 @@ use std::marker::PhantomData;
use std::ptr::NonNull;
use std::{fmt, mem};
-/// An owned handle to the task, tracked by ref count
+/// An owned handle to the task, tracked by ref count.
#[repr(transparent)]
pub(crate) struct Task<S: 'static> {
raw: RawTask,
@@ -211,7 +211,7 @@ pub(crate) struct UnownedTask<S: 'static> {
unsafe impl<S> Send for UnownedTask<S> {}
unsafe impl<S> Sync for UnownedTask<S> {}
-/// Task result sent back
+/// Task result sent back.
pub(crate) type Result<T> = std::result::Result<T, JoinError>;
pub(crate) trait Schedule: Sync + Sized + 'static {
@@ -260,7 +260,7 @@ cfg_rt! {
(task, notified, join)
}
- /// Create a new task with an associated join handle. This method is used
+ /// Creates a new task with an associated join handle. This method is used
/// only when the task is not going to be stored in an `OwnedTasks` list.
///
/// Currently only blocking tasks use this method.
@@ -327,7 +327,7 @@ cfg_rt_multi_thread! {
}
impl<S: Schedule> Task<S> {
- /// Pre-emptively cancel the task as part of the shutdown process.
+ /// Pre-emptively cancels the task as part of the shutdown process.
pub(crate) fn shutdown(self) {
let raw = self.raw;
mem::forget(self);
@@ -336,7 +336,7 @@ impl<S: Schedule> Task<S> {
}
impl<S: Schedule> LocalNotified<S> {
- /// Run the task
+ /// Runs the task.
pub(crate) fn run(self) {
let raw = self.task.raw;
mem::forget(self);
@@ -420,7 +420,7 @@ impl<S> fmt::Debug for Notified<S> {
/// # Safety
///
-/// Tasks are pinned
+/// Tasks are pinned.
unsafe impl<S> linked_list::Link for Task<S> {
type Handle = Task<S>;
type Target = Header;
diff --git a/src/runtime/task/raw.rs b/src/runtime/task/raw.rs
index 8c2c3f7..fbc9574 100644
--- a/src/runtime/task/raw.rs
+++ b/src/runtime/task/raw.rs
@@ -10,22 +10,22 @@ pub(super) struct RawTask {
}
pub(super) struct Vtable {
- /// Poll the future
+ /// Polls the future.
pub(super) poll: unsafe fn(NonNull<Header>),
- /// Deallocate the memory
+ /// Deallocates the memory.
pub(super) dealloc: unsafe fn(NonNull<Header>),
- /// Read the task output, if complete
+ /// Reads the task output, if complete.
pub(super) try_read_output: unsafe fn(NonNull<Header>, *mut (), &Waker),
- /// The join handle has been dropped
+ /// The join handle has been dropped.
pub(super) drop_join_handle_slow: unsafe fn(NonNull<Header>),
- /// The task is remotely aborted
+ /// The task is remotely aborted.
pub(super) remote_abort: unsafe fn(NonNull<Header>),
- /// Scheduler is being shutdown
+ /// Scheduler is being shutdown.
pub(super) shutdown: unsafe fn(NonNull<Header>),
}
diff --git a/src/runtime/task/state.rs b/src/runtime/task/state.rs
index 059a7f9..c2d5b28 100644
--- a/src/runtime/task/state.rs
+++ b/src/runtime/task/state.rs
@@ -8,7 +8,7 @@ pub(super) struct State {
val: AtomicUsize,
}
-/// Current state value
+/// Current state value.
#[derive(Copy, Clone)]
pub(super) struct Snapshot(usize);
@@ -19,20 +19,20 @@ const RUNNING: usize = 0b0001;
/// The task is complete.
///
-/// Once this bit is set, it is never unset
+/// Once this bit is set, it is never unset.
const COMPLETE: usize = 0b0010;
-/// Extracts the task's lifecycle value from the state
+/// Extracts the task's lifecycle value from the state.
const LIFECYCLE_MASK: usize = 0b11;
/// Flag tracking if the task has been pushed into a run queue.
const NOTIFIED: usize = 0b100;
-/// The join handle is still around
+/// The join handle is still around.
#[allow(clippy::unusual_byte_groupings)] // https://github.com/rust-lang/rust-clippy/issues/6556
const JOIN_INTEREST: usize = 0b1_000;
-/// A join handle waker has been set
+/// A join handle waker has been set.
#[allow(clippy::unusual_byte_groupings)] // https://github.com/rust-lang/rust-clippy/issues/6556
const JOIN_WAKER: usize = 0b10_000;
@@ -40,19 +40,19 @@ const JOIN_WAKER: usize = 0b10_000;
#[allow(clippy::unusual_byte_groupings)] // https://github.com/rust-lang/rust-clippy/issues/6556
const CANCELLED: usize = 0b100_000;
-/// All bits
+/// All bits.
const STATE_MASK: usize = LIFECYCLE_MASK | NOTIFIED | JOIN_INTEREST | JOIN_WAKER | CANCELLED;
/// Bits used by the ref count portion of the state.
const REF_COUNT_MASK: usize = !STATE_MASK;
-/// Number of positions to shift the ref count
+/// Number of positions to shift the ref count.
const REF_COUNT_SHIFT: usize = REF_COUNT_MASK.count_zeros() as usize;
-/// One ref count
+/// One ref count.
const REF_ONE: usize = 1 << REF_COUNT_SHIFT;
-/// State a task is initialized with
+/// State a task is initialized with.
///
/// A task is initialized with three references:
///
@@ -96,7 +96,7 @@ pub(super) enum TransitionToNotifiedByRef {
/// All transitions are performed via RMW operations. This establishes an
/// unambiguous modification order.
impl State {
- /// Return a task's initial state
+ /// Returns a task's initial state.
pub(super) fn new() -> State {
// The raw task returned by this method has a ref-count of three. See
// the comment on INITIAL_STATE for more.
@@ -110,7 +110,7 @@ impl State {
Snapshot(self.val.load(Acquire))
}
- /// Attempt to transition the lifecycle to `Running`. This sets the
+ /// Attempts to transition the lifecycle to `Running`. This sets the
/// notified bit to false so notifications during the poll can be detected.
pub(super) fn transition_to_running(&self) -> TransitionToRunning {
self.fetch_update_action(|mut next| {
@@ -190,7 +190,7 @@ impl State {
Snapshot(prev.0 ^ DELTA)
}
- /// Transition from `Complete` -> `Terminal`, decrementing the reference
+ /// Transitions from `Complete` -> `Terminal`, decrementing the reference
/// count the specified number of times.
///
/// Returns true if the task should be deallocated.
@@ -270,10 +270,10 @@ impl State {
})
}
- /// Set the cancelled bit and transition the state to `NOTIFIED` if idle.
+ /// Sets the cancelled bit and transitions the state to `NOTIFIED` if idle.
///
/// Returns `true` if the task needs to be submitted to the pool for
- /// execution
+ /// execution.
pub(super) fn transition_to_notified_and_cancel(&self) -> bool {
self.fetch_update_action(|mut snapshot| {
if snapshot.is_cancelled() || snapshot.is_complete() {
@@ -306,7 +306,7 @@ impl State {
})
}
- /// Set the `CANCELLED` bit and attempt to transition to `Running`.
+ /// Sets the `CANCELLED` bit and attempts to transition to `Running`.
///
/// Returns `true` if the transition to `Running` succeeded.
pub(super) fn transition_to_shutdown(&self) -> bool {
@@ -330,7 +330,7 @@ impl State {
}
/// Optimistically tries to swap the state assuming the join handle is
- /// __immediately__ dropped on spawn
+ /// __immediately__ dropped on spawn.
pub(super) fn drop_join_handle_fast(&self) -> Result<(), ()> {
use std::sync::atomic::Ordering::Relaxed;
@@ -352,7 +352,7 @@ impl State {
.map_err(|_| ())
}
- /// Try to unset the JOIN_INTEREST flag.
+ /// Tries to unset the JOIN_INTEREST flag.
///
/// Returns `Ok` if the operation happens before the task transitions to a
/// completed state, `Err` otherwise.
@@ -371,7 +371,7 @@ impl State {
})
}
- /// Set the `JOIN_WAKER` bit.
+ /// Sets the `JOIN_WAKER` bit.
///
/// Returns `Ok` if the bit is set, `Err` otherwise. This operation fails if
/// the task has completed.
generated by cgit v1.2.3 (git 2.25.1) at 2024-07-15 22:52:32 +0000