diff --git a/lightproc/examples/proc_panic.rs b/lightproc/examples/proc_panic.rs index 6aa4b9c9..f9d1164e 100644 --- a/lightproc/examples/proc_panic.rs +++ b/lightproc/examples/proc_panic.rs @@ -11,7 +11,7 @@ where R: Send + 'static, { lazy_static! { - // A channel that holds scheduled tasks. + // A channel that holds scheduled procs. static ref QUEUE: Sender = { let (sender, receiver) = unbounded::(); diff --git a/lightproc/src/lightproc.rs b/lightproc/src/lightproc.rs index b4a1113d..9693b34e 100644 --- a/lightproc/src/lightproc.rs +++ b/lightproc/src/lightproc.rs @@ -13,7 +13,7 @@ use crate::recoverable_handle::RecoverableHandle; use std::panic::AssertUnwindSafe; pub struct LightProc { - /// A pointer to the heap-allocated task. + /// A pointer to the heap-allocated proc. pub(crate) raw_proc: NonNull<()>, } @@ -42,13 +42,13 @@ impl LightProc { R: Send + 'static, S: Fn(LightProc) + Send + Sync + 'static, { - let raw_task = RawProc::allocate(stack, future, schedule); - let task = LightProc { raw_proc: raw_task }; + let raw_proc = RawProc::allocate(stack, future, schedule); + let proc = LightProc { raw_proc: raw_proc }; let handle = ProcHandle { - raw_proc: raw_task, + raw_proc: raw_proc, _marker: PhantomData, }; - (task, handle) + (proc, handle) } pub fn schedule(self) { @@ -97,13 +97,13 @@ impl Drop for LightProc { let pdata = ptr as *const ProcData; unsafe { - // Cancel the task. + // Cancel the proc. (*pdata).cancel(); // Drop the future. ((*pdata).vtable.drop_future)(ptr); - // Drop the task reference. + // Drop the proc reference. ((*pdata).vtable.decrement)(ptr); } } @@ -114,7 +114,7 @@ impl fmt::Debug for LightProc { let ptr = self.raw_proc.as_ptr(); let pdata = ptr as *const ProcData; - f.debug_struct("Task") + f.debug_struct("LightProc") .field("pdata", unsafe { &(*pdata) }) .field("stack", self.stack()) .finish() diff --git a/lightproc/src/proc_data.rs b/lightproc/src/proc_data.rs index a52d5a4d..42bdde1b 100644 --- a/lightproc/src/proc_data.rs +++ b/lightproc/src/proc_data.rs @@ -11,42 +11,42 @@ use crate::proc_stack::*; use crate::proc_vtable::ProcVTable; use crate::state::*; -/// The pdata of a task. +/// The pdata of a proc. /// -/// This pdata is stored right at the beginning of every heap-allocated task. +/// This pdata is stored right at the beginning of every heap-allocated proc. pub(crate) struct ProcData { - /// Current state of the task. + /// Current state of the proc. /// /// Contains flags representing the current state and the reference count. pub(crate) state: AtomicUsize, - /// The task that is blocked on the `JoinHandle`. + /// The proc that is blocked on the `ProcHandle`. /// - /// This waker needs to be woken once the task completes or is closed. + /// This waker needs to be woken once the proc completes or is closed. pub(crate) awaiter: Cell>, /// The virtual table. /// /// In addition to the actual waker virtual table, it also contains pointers to several other - /// methods necessary for bookkeeping the heap-allocated task. + /// methods necessary for bookkeeping the heap-allocated proc. pub(crate) vtable: &'static ProcVTable, } impl ProcData { - /// Cancels the task. + /// Cancels the proc. /// - /// This method will only mark the task as closed and will notify the awaiter, but it won't - /// reschedule the task if it's not completed. + /// This method will only mark the proc as closed and will notify the awaiter, but it won't + /// reschedule the proc if it's not completed. pub(crate) fn cancel(&self) { let mut state = self.state.load(Ordering::Acquire); loop { - // If the task has been completed or closed, it can't be cancelled. + // If the proc has been completed or closed, it can't be cancelled. if state & (COMPLETED | CLOSED) != 0 { break; } - // Mark the task as closed. + // Mark the proc as closed. match self.state.compare_exchange_weak( state, state | CLOSED, @@ -54,7 +54,7 @@ impl ProcData { Ordering::Acquire, ) { Ok(_) => { - // Notify the awaiter that the task has been closed. + // Notify the awaiter that the proc has been closed. if state & AWAITER != 0 { self.notify(); } @@ -66,7 +66,7 @@ impl ProcData { } } - /// Notifies the task blocked on the task. + /// Notifies the proc blocked on the proc. /// /// If there is a registered waker, it will be removed from the pdata and woken. #[inline] @@ -77,7 +77,7 @@ impl ProcData { } } - /// Notifies the task blocked on the task unless its waker matches `current`. + /// Notifies the proc blocked on the proc unless its waker matches `current`. /// /// If there is a registered waker, it will be removed from the pdata. #[inline] diff --git a/lightproc/src/proc_handle.rs b/lightproc/src/proc_handle.rs index 915ec72e..2327185a 100644 --- a/lightproc/src/proc_handle.rs +++ b/lightproc/src/proc_handle.rs @@ -10,14 +10,14 @@ use crate::proc_data::ProcData; use crate::proc_stack::*; use crate::state::*; -/// A handle that awaits the result of a task. +/// A handle that awaits the result of a proc. /// /// This type is a future that resolves to an `Option` where: /// -/// * `None` indicates the task has panicked or was cancelled -/// * `Some(res)` indicates the task has completed with `res` +/// * `None` indicates the proc has panicked or was cancelled +/// * `Some(res)` indicates the proc has completed with `res` pub struct ProcHandle { - /// A raw task pointer. + /// A raw proc pointer. pub(crate) raw_proc: NonNull<()>, /// A marker capturing the generic type `R`. @@ -30,11 +30,11 @@ unsafe impl Sync for ProcHandle {} impl Unpin for ProcHandle {} impl ProcHandle { - /// Cancels the task. + /// Cancels the proc. /// - /// If the task has already completed, calling this method will have no effect. + /// If the proc has already completed, calling this method will have no effect. /// - /// When a task is cancelled, its future cannot be polled again and will be dropped instead. + /// When a proc is cancelled, its future cannot be polled again and will be dropped instead. pub fn cancel(&self) { let ptr = self.raw_proc.as_ptr(); let pdata = ptr as *const ProcData; @@ -43,19 +43,19 @@ impl ProcHandle { let mut state = (*pdata).state.load(Ordering::Acquire); loop { - // If the task has been completed or closed, it can't be cancelled. + // If the proc has been completed or closed, it can't be cancelled. if state & (COMPLETED | CLOSED) != 0 { break; } - // If the task is not scheduled nor running, we'll need to schedule it. + // If the proc is not scheduled nor running, we'll need to schedule it. let new = if state & (SCHEDULED | RUNNING) == 0 { (state | SCHEDULED | CLOSED) + REFERENCE } else { state | CLOSED }; - // Mark the task as closed. + // Mark the proc as closed. match (*pdata).state.compare_exchange_weak( state, new, @@ -63,13 +63,13 @@ impl ProcHandle { Ordering::Acquire, ) { Ok(_) => { - // If the task is not scheduled nor running, schedule it so that its future + // If the proc is not scheduled nor running, schedule it so that its future // gets dropped by the executor. if state & (SCHEDULED | RUNNING) == 0 { ((*pdata).vtable.schedule)(ptr); } - // Notify the awaiter that the task has been closed. + // Notify the awaiter that the proc has been closed. if state & AWAITER != 0 { (*pdata).notify(); } @@ -82,7 +82,7 @@ impl ProcHandle { } } - /// Returns a reference to the stack stored inside the task. + /// Returns a reference to the stack stored inside the proc. pub fn stack(&self) -> &ProcStack { let offset = ProcData::offset_stack(); let ptr = self.raw_proc.as_ptr(); @@ -103,8 +103,8 @@ impl Drop for ProcHandle { let mut output = None; unsafe { - // Optimistically assume the `JoinHandle` is being dropped just after creating the - // task. This is a common case so if the handle is not used, the overhead of it is only + // Optimistically assume the `ProcHandle` is being dropped just after creating the + // proc. This is a common case so if the handle is not used, the overhead of it is only // one compare-exchange operation. if let Err(mut state) = (*pdata).state.compare_exchange_weak( SCHEDULED | HANDLE | REFERENCE, @@ -113,10 +113,10 @@ impl Drop for ProcHandle { Ordering::Acquire, ) { loop { - // If the task has been completed but not yet closed, that means its output + // If the proc has been completed but not yet closed, that means its output // must be dropped. if state & COMPLETED != 0 && state & CLOSED == 0 { - // Mark the task as closed in order to grab its output. + // Mark the proc as closed in order to grab its output. match (*pdata).state.compare_exchange_weak( state, state | CLOSED, @@ -133,7 +133,7 @@ impl Drop for ProcHandle { Err(s) => state = s, } } else { - // If this is the last reference to the task and it's not closed, then + // If this is the last reference to the proc and it's not closed, then // close it and schedule one more time so that its future gets dropped by // the executor. let new = if state & (!(REFERENCE - 1) | CLOSED) == 0 { @@ -150,7 +150,7 @@ impl Drop for ProcHandle { Ordering::Acquire, ) { Ok(_) => { - // If this is the last reference to the task, we need to either + // If this is the last reference to the proc, we need to either // schedule dropping its future or destroy it. if state & !(REFERENCE - 1) == 0 { if state & CLOSED == 0 { @@ -169,7 +169,7 @@ impl Drop for ProcHandle { } } - // Drop the output if it was taken out of the task. + // Drop the output if it was taken out of the proc. drop(output); } } @@ -185,39 +185,39 @@ impl Future for ProcHandle { let mut state = (*pdata).state.load(Ordering::Acquire); loop { - // If the task has been closed, notify the awaiter and return `None`. + // If the proc has been closed, notify the awaiter and return `None`. if state & CLOSED != 0 { - // Even though the awaiter is most likely the current task, it could also be - // another task. + // Even though the awaiter is most likely the current proc, it could also be + // another proc. (*pdata).notify_unless(cx.waker()); return Poll::Ready(None); } - // If the task is not completed, register the current task. + // If the proc is not completed, register the current proc. if state & COMPLETED == 0 { - // Replace the waker with one associated with the current task. We need a + // Replace the waker with one associated with the current proc. We need a // safeguard against panics because dropping the previous waker can panic. (*pdata).swap_awaiter(Some(cx.waker().clone())); - // Reload the state after registering. It is possible that the task became + // Reload the state after registering. It is possible that the proc became // completed or closed just before registration so we need to check for that. state = (*pdata).state.load(Ordering::Acquire); - // If the task has been closed, notify the awaiter and return `None`. + // If the proc has been closed, notify the awaiter and return `None`. if state & CLOSED != 0 { - // Even though the awaiter is most likely the current task, it could also - // be another task. + // Even though the awaiter is most likely the current proc, it could also + // be another proc. (*pdata).notify_unless(cx.waker()); return Poll::Ready(None); } - // If the task is still not completed, we're blocked on it. + // If the proc is still not completed, we're blocked on it. if state & COMPLETED == 0 { return Poll::Pending; } } - // Since the task is now completed, mark it as closed in order to grab its output. + // Since the proc is now completed, mark it as closed in order to grab its output. match (*pdata).state.compare_exchange( state, state | CLOSED, @@ -226,12 +226,12 @@ impl Future for ProcHandle { ) { Ok(_) => { // Notify the awaiter. Even though the awaiter is most likely the current - // task, it could also be another task. + // proc, it could also be another proc. if state & AWAITER != 0 { (*pdata).notify_unless(cx.waker()); } - // Take the output from the task. + // Take the output from the proc. let output = ((*pdata).vtable.get_output)(ptr) as *mut R; return Poll::Ready(Some(output.read())); } @@ -247,7 +247,7 @@ impl fmt::Debug for ProcHandle { let ptr = self.raw_proc.as_ptr(); let pdata = ptr as *const ProcData; - f.debug_struct("JoinHandle") + f.debug_struct("ProcHandle") .field("pdata", unsafe { &(*pdata) }) .finish() } diff --git a/lightproc/src/proc_layout.rs b/lightproc/src/proc_layout.rs index d51b36d0..df719784 100644 --- a/lightproc/src/proc_layout.rs +++ b/lightproc/src/proc_layout.rs @@ -2,18 +2,18 @@ use std::alloc::Layout; #[derive(Clone, Copy)] pub(crate) struct TaskLayout { - /// Memory layout of the whole task. + /// Memory layout of the whole proc. pub(crate) layout: Layout, - /// Offset into the task at which the stack is stored. + /// Offset into the proc at which the stack is stored. pub(crate) offset_t: usize, - /// Offset into the task at which the schedule function is stored. + /// Offset into the proc at which the schedule function is stored. pub(crate) offset_s: usize, - /// Offset into the task at which the future is stored. + /// Offset into the proc at which the future is stored. pub(crate) offset_f: usize, - /// Offset into the task at which the output is stored. + /// Offset into the proc at which the output is stored. pub(crate) offset_r: usize, } diff --git a/lightproc/src/proc_vtable.rs b/lightproc/src/proc_vtable.rs index ecf1231c..1dea6719 100644 --- a/lightproc/src/proc_vtable.rs +++ b/lightproc/src/proc_vtable.rs @@ -1,25 +1,25 @@ use std::task::RawWakerVTable; -/// The vtable for a task. +/// The vtable for a proc. pub(crate) struct ProcVTable { /// The raw waker vtable. pub(crate) raw_waker: RawWakerVTable, - /// Schedules the task. + /// Schedules the proc. pub(crate) schedule: unsafe fn(*const ()), - /// Drops the future inside the task. + /// Drops the future inside the proc. pub(crate) drop_future: unsafe fn(*const ()), /// Returns a pointer to the output stored after completion. pub(crate) get_output: unsafe fn(*const ()) -> *const (), - /// Drops a waker or a task. + /// Drops a waker or a proc. pub(crate) decrement: unsafe fn(ptr: *const ()), - /// Destroys the task. + /// Destroys the proc. pub(crate) destroy: unsafe fn(*const ()), - /// Runs the task. + /// Runs the proc. pub(crate) run: unsafe fn(*const ()), } diff --git a/lightproc/src/raw_proc.rs b/lightproc/src/raw_proc.rs index c45831d3..8364cf85 100644 --- a/lightproc/src/raw_proc.rs +++ b/lightproc/src/raw_proc.rs @@ -18,7 +18,7 @@ use crate::state::*; use std::panic::AssertUnwindSafe; -/// Raw pointers to the fields of a task. +/// Raw pointers to the fields of a proc. pub(crate) struct RawProc { pub(crate) pdata: *const ProcData, pub(crate) schedule: *const S, @@ -47,23 +47,23 @@ where R: Send + 'static, S: Fn(LightProc) + Send + Sync + 'static, { - /// Allocates a task with the given `future` and `schedule` function. + /// Allocates a proc with the given `future` and `schedule` function. /// - /// It is assumed there are initially only the `Task` reference and the `JoinHandle`. + /// It is assumed there are initially only the `LightProc` reference and the `ProcHandle`. pub(crate) fn allocate(stack: ProcStack, future: F, schedule: S) -> NonNull<()> { - // Compute the layout of the task for allocation. Abort if the computation fails. - let task_layout = Self::task_layout(); + // Compute the layout of the proc for allocation. Abort if the computation fails. + let proc_layout = Self::proc_layout(); unsafe { - // Allocate enough space for the entire task. - let raw_task = match NonNull::new(alloc::alloc(task_layout.layout) as *mut ()) { + // Allocate enough space for the entire proc. + let raw_proc = match NonNull::new(alloc::alloc(proc_layout.layout) as *mut ()) { None => std::process::abort(), Some(p) => p, }; - let raw = Self::from_ptr(raw_task.as_ptr()); + let raw = Self::from_ptr(raw_proc.as_ptr()); - // Write the pdata as the first field of the task. + // Write the pdata as the first field of the proc. (raw.pdata as *mut ProcData).write(ProcData { state: AtomicUsize::new(SCHEDULED | HANDLE | REFERENCE), awaiter: Cell::new(None), @@ -83,39 +83,39 @@ where }, }); - // Write the stack as the second field of the task. + // Write the stack as the second field of the proc. (raw.stack as *mut ProcStack).write(stack); - // Write the schedule function as the third field of the task. + // Write the schedule function as the third field of the proc. (raw.schedule as *mut S).write(schedule); - // Write the future as the fourth field of the task. + // Write the future as the fourth field of the proc. raw.future.write(future); - raw_task + raw_proc } } - /// Creates a `RawTask` from a raw task pointer. + /// Creates a `RawProc` from a raw proc pointer. #[inline] pub(crate) fn from_ptr(ptr: *const ()) -> Self { - let task_layout = Self::task_layout(); + let proc_layout = Self::proc_layout(); let p = ptr as *const u8; unsafe { Self { pdata: p as *const ProcData, - stack: p.add(task_layout.offset_t) as *mut ProcStack, - schedule: p.add(task_layout.offset_s) as *const S, - future: p.add(task_layout.offset_f) as *mut F, - output: p.add(task_layout.offset_r) as *mut R, + stack: p.add(proc_layout.offset_t) as *mut ProcStack, + schedule: p.add(proc_layout.offset_s) as *const S, + future: p.add(proc_layout.offset_f) as *mut F, + output: p.add(proc_layout.offset_r) as *mut R, } } } - /// Returns the memory layout for a task. + /// Returns the memory layout for a proc. #[inline] - fn task_layout() -> TaskLayout { + fn proc_layout() -> TaskLayout { let layout_pdata = Layout::new::(); let layout_t = Layout::new::(); let layout_s = Layout::new::(); @@ -149,15 +149,15 @@ where let mut state = (*raw.pdata).state.load(Ordering::Acquire); loop { - // If the task is completed or closed, it can't be woken. + // If the proc is completed or closed, it can't be woken. if state & (COMPLETED | CLOSED) != 0 { // Drop the waker. Self::decrement(ptr); break; } - // If the task is already scheduled, we just need to synchronize with the thread that - // will run the task by "publishing" our current view of the memory. + // If the proc is already scheduled, we just need to synchronize with the thread that + // will run the proc by "publishing" our current view of the memory. if state & SCHEDULED != 0 { // Update the state without actually modifying it. match (*raw.pdata).state.compare_exchange_weak( @@ -174,7 +174,7 @@ where Err(s) => state = s, } } else { - // Mark the task as scheduled. + // Mark the proc as scheduled. match (*raw.pdata).state.compare_exchange_weak( state, state | SCHEDULED, @@ -182,14 +182,14 @@ where Ordering::Acquire, ) { Ok(_) => { - // If the task is not yet scheduled and isn't currently running, now is the + // If the proc is not yet scheduled and isn't currently running, now is the // time to schedule it. if state & (SCHEDULED | RUNNING) == 0 { - // Schedule the task. - let task = LightProc { + // Schedule the proc. + let proc = LightProc { raw_proc: NonNull::new_unchecked(ptr as *mut ()), }; - (*raw.schedule)(task); + (*raw.schedule)(proc); } else { // Drop the waker. Self::decrement(ptr); @@ -210,13 +210,13 @@ where let mut state = (*raw.pdata).state.load(Ordering::Acquire); loop { - // If the task is completed or closed, it can't be woken. + // If the proc is completed or closed, it can't be woken. if state & (COMPLETED | CLOSED) != 0 { break; } - // If the task is already scheduled, we just need to synchronize with the thread that - // will run the task by "publishing" our current view of the memory. + // If the proc is already scheduled, we just need to synchronize with the thread that + // will run the proc by "publishing" our current view of the memory. if state & SCHEDULED != 0 { // Update the state without actually modifying it. match (*raw.pdata).state.compare_exchange_weak( @@ -229,14 +229,14 @@ where Err(s) => state = s, } } else { - // If the task is not scheduled nor running, we'll need to schedule after waking. + // If the proc is not scheduled nor running, we'll need to schedule after waking. let new = if state & (SCHEDULED | RUNNING) == 0 { (state | SCHEDULED) + REFERENCE } else { state | SCHEDULED }; - // Mark the task as scheduled. + // Mark the proc as scheduled. match (*raw.pdata).state.compare_exchange_weak( state, new, @@ -244,18 +244,18 @@ where Ordering::Acquire, ) { Ok(_) => { - // If the task is not scheduled nor running, now is the time to schedule. + // If the proc is not scheduled nor running, now is the time to schedule. if state & (SCHEDULED | RUNNING) == 0 { // If the reference count overflowed, abort. if state > isize::max_value() as usize { std::process::abort(); } - // Schedule the task. - let task = LightProc { + // Schedule the proc. + let proc = LightProc { raw_proc: NonNull::new_unchecked(ptr as *mut ()), }; - (*raw.schedule)(task); + (*raw.schedule)(proc); } break; @@ -283,10 +283,10 @@ where RawWaker::new(ptr, raw_waker) } - /// Drops a waker or a task. + /// Drops a waker or a proc. /// /// This function will decrement the reference count. If it drops down to zero and the - /// associated join handle has been dropped too, then the task gets destroyed. + /// associated join handle has been dropped too, then the proc gets destroyed. #[inline] unsafe fn decrement(ptr: *const ()) { let raw = Self::from_ptr(ptr); @@ -294,16 +294,16 @@ where // Decrement the reference count. let new = (*raw.pdata).state.fetch_sub(REFERENCE, Ordering::AcqRel) - REFERENCE; - // If this was the last reference to the task and the `JoinHandle` has been dropped as - // well, then destroy the task. + // If this was the last reference to the proc and the `ProcHandle` has been dropped as + // well, then destroy the proc. if new & !(REFERENCE - 1) == 0 && new & HANDLE == 0 { Self::destroy(ptr); } } - /// Schedules a task for running. + /// Schedules a proc for running. /// - /// This function doesn't modify the state of the task. It only passes the task reference to + /// This function doesn't modify the state of the proc. It only passes the proc reference to /// its schedule function. unsafe fn schedule(ptr: *const ()) { let raw = Self::from_ptr(ptr); @@ -313,7 +313,7 @@ where }); } - /// Drops the future inside a task. + /// Drops the future inside a proc. #[inline] unsafe fn drop_future(ptr: *const ()) { let raw = Self::from_ptr(ptr); @@ -322,20 +322,20 @@ where raw.future.drop_in_place(); } - /// Returns a pointer to the output inside a task. + /// Returns a pointer to the output inside a proc. unsafe fn get_output(ptr: *const ()) -> *const () { let raw = Self::from_ptr(ptr); raw.output as *const () } - /// Cleans up task's resources and deallocates it. + /// Cleans up proc's resources and deallocates it. /// - /// If the task has not been closed, then its future or the output will be dropped. The + /// If the proc has not been closed, then its future or the output will be dropped. The /// schedule function and the stack get dropped too. #[inline] unsafe fn destroy(ptr: *const ()) { let raw = Self::from_ptr(ptr); - let task_layout = Self::task_layout(); + let proc_layout = Self::proc_layout(); // We need a safeguard against panics because destructors can panic. // Drop the schedule function. @@ -344,18 +344,18 @@ where // Drop the stack. (raw.stack as *mut ProcStack).drop_in_place(); - // Finally, deallocate the memory reserved by the task. - alloc::dealloc(ptr as *mut u8, task_layout.layout); + // Finally, deallocate the memory reserved by the proc. + alloc::dealloc(ptr as *mut u8, proc_layout.layout); } - /// Runs a task. + /// Runs a proc. /// - /// If polling its future panics, the task will be closed and the panic propagated into the + /// If polling its future panics, the proc will be closed and the panic propagated into the /// caller. unsafe fn run(ptr: *const ()) { let raw = Self::from_ptr(ptr); - // Create a context from the raw task pointer and the vtable inside the its pdata. + // Create a context from the raw proc pointer and the vtable inside the its pdata. let waker = ManuallyDrop::new(Waker::from_raw(RawWaker::new( ptr, &(*raw.pdata).vtable.raw_waker, @@ -364,11 +364,11 @@ where let mut state = (*raw.pdata).state.load(Ordering::Acquire); - // Update the task's state before polling its future. + // Update the proc's state before polling its future. loop { - // If the task has been closed, drop the task reference and return. + // If the proc has been closed, drop the proc reference and return. if state & CLOSED != 0 { - // Notify the awaiter that the task has been closed. + // Notify the awaiter that the proc has been closed. if state & AWAITER != 0 { (*raw.pdata).notify(); } @@ -376,12 +376,12 @@ where // Drop the future. Self::drop_future(ptr); - // Drop the task reference. + // Drop the proc reference. Self::decrement(ptr); return; } - // Mark the task as unscheduled and running. + // Mark the proc as unscheduled and running. match (*raw.pdata).state.compare_exchange_weak( state, (state & !SCHEDULED) | RUNNING, @@ -397,7 +397,7 @@ where } } - // Poll the inner future, but surround it with a guard that closes the task in case polling + // Poll the inner future, but surround it with a guard that closes the proc in case polling // panics. let guard = Guard(raw); @@ -417,7 +417,7 @@ where // A place where the output will be stored in case it needs to be dropped. let mut output = None; - // The task is now completed. + // The proc is now completed. loop { // If the handle is dropped, we'll need to close it and drop the output. let new = if state & HANDLE == 0 { @@ -426,7 +426,7 @@ where (state & !RUNNING & !SCHEDULED) | COMPLETED }; - // Mark the task as not running and completed. + // Mark the proc as not running and completed. match (*raw.pdata).state.compare_exchange_weak( state, new, @@ -434,14 +434,14 @@ where Ordering::Acquire, ) { Ok(_) => { - // If the handle is dropped or if the task was closed while running, + // If the handle is dropped or if the proc was closed while running, // now it's time to drop the output. if state & HANDLE == 0 || state & CLOSED != 0 { // Read the output. output = Some(raw.output.read()); } - // Notify the awaiter that the task has been completed. + // Notify the awaiter that the proc has been completed. if state & AWAITER != 0 { (*raw.pdata).notify(); } @@ -450,7 +450,7 @@ where (*after_complete_cb.clone())(); } - // Drop the task reference. + // Drop the proc reference. Self::decrement(ptr); break; } @@ -458,13 +458,13 @@ where } } - // Drop the output if it was taken out of the task. + // Drop the output if it was taken out of the proc. drop(output); } Poll::Pending => { - // The task is still not completed. + // The proc is still not completed. loop { - // If the task was closed while running, we'll need to unschedule in case it + // If the proc was closed while running, we'll need to unschedule in case it // was woken and then clean up its resources. let new = if state & CLOSED != 0 { state & !RUNNING & !SCHEDULED @@ -472,7 +472,7 @@ where state & !RUNNING }; - // Mark the task as not running. + // Mark the proc as not running. match (*raw.pdata).state.compare_exchange_weak( state, new, @@ -480,22 +480,22 @@ where Ordering::Acquire, ) { Ok(state) => { - // If the task was closed while running, we need to drop its future. - // If the task was woken while running, we need to schedule it. - // Otherwise, we just drop the task reference. + // If the proc was closed while running, we need to drop its future. + // If the proc was woken while running, we need to schedule it. + // Otherwise, we just drop the proc reference. if state & CLOSED != 0 { - // The thread that closed the task didn't drop the future because + // The thread that closed the proc didn't drop the future because // it was running so now it's our responsibility to do so. Self::drop_future(ptr); - // Drop the task reference. + // Drop the proc reference. Self::decrement(ptr); } else if state & SCHEDULED != 0 { - // The thread that has woken the task didn't reschedule it because + // The thread that has woken the proc didn't reschedule it because // it was running so now it's our responsibility to do so. Self::schedule(ptr); } else { - // Drop the task reference. + // Drop the proc reference. Self::decrement(ptr); } break; @@ -506,7 +506,7 @@ where } } - /// A guard that closes the task if polling its future panics. + /// A guard that closes the proc if polling its future panics. struct Guard(RawProc) where F: Future + Send + 'static, @@ -527,23 +527,23 @@ where let mut state = (*raw.pdata).state.load(Ordering::Acquire); loop { - // If the task was closed while running, then unschedule it, drop its - // future, and drop the task reference. + // If the proc was closed while running, then unschedule it, drop its + // future, and drop the proc reference. if state & CLOSED != 0 { - // We still need to unschedule the task because it is possible it was + // We still need to unschedule the proc because it is possible it was // woken while running. (*raw.pdata).state.fetch_and(!SCHEDULED, Ordering::AcqRel); - // The thread that closed the task didn't drop the future because it + // The thread that closed the proc didn't drop the future because it // was running so now it's our responsibility to do so. RawProc::::drop_future(ptr); - // Drop the task reference. + // Drop the proc reference. RawProc::::decrement(ptr); break; } - // Mark the task as not running, not scheduled, and closed. + // Mark the proc as not running, not scheduled, and closed. match (*raw.pdata).state.compare_exchange_weak( state, (state & !RUNNING & !SCHEDULED) | CLOSED, @@ -551,15 +551,15 @@ where Ordering::Acquire, ) { Ok(state) => { - // Drop the future because the task is now closed. + // Drop the future because the proc is now closed. RawProc::::drop_future(ptr); - // Notify the awaiter that the task has been closed. + // Notify the awaiter that the proc has been closed. if state & AWAITER != 0 { (*raw.pdata).notify(); } - // Drop the task reference. + // Drop the proc reference. RawProc::::decrement(ptr); break; } diff --git a/lightproc/src/state.rs b/lightproc/src/state.rs index d6ce34fd..41696297 100644 --- a/lightproc/src/state.rs +++ b/lightproc/src/state.rs @@ -1,52 +1,52 @@ -/// Set if the task is scheduled for running. +/// Set if the proc is scheduled for running. /// -/// A task is considered to be scheduled whenever its `Task` reference exists. It is in scheduled -/// state at the moment of creation and when it gets unapused either by its `JoinHandle` or woken +/// A proc is considered to be scheduled whenever its `LightProc` reference exists. It is in scheduled +/// state at the moment of creation and when it gets unapused either by its `ProcHandle` or woken /// by a `Waker`. /// -/// This flag can't be set when the task is completed. However, it can be set while the task is +/// This flag can't be set when the proc is completed. However, it can be set while the proc is /// running, in which case it will be rescheduled as soon as polling finishes. pub(crate) const SCHEDULED: usize = 1 << 0; -/// Set if the task is running. +/// Set if the proc is running. /// -/// A task is running state while its future is being polled. +/// A proc is running state while its future is being polled. /// -/// This flag can't be set when the task is completed. However, it can be in scheduled state while +/// This flag can't be set when the proc is completed. However, it can be in scheduled state while /// it is running, in which case it will be rescheduled when it stops being polled. pub(crate) const RUNNING: usize = 1 << 1; -/// Set if the task has been completed. +/// Set if the proc has been completed. /// /// This flag is set when polling returns `Poll::Ready`. The output of the future is then stored -/// inside the task until it becomes stopped. In fact, `JoinHandle` picks the output up by marking -/// the task as stopped. +/// inside the proc until it becomes stopped. In fact, `ProcHandle` picks the output up by marking +/// the proc as stopped. /// -/// This flag can't be set when the task is scheduled or completed. +/// This flag can't be set when the proc is scheduled or completed. pub(crate) const COMPLETED: usize = 1 << 2; -/// Set if the task is closed. +/// Set if the proc is closed. /// -/// If a task is closed, that means its either cancelled or its output has been consumed by the -/// `JoinHandle`. A task becomes closed when: +/// If a proc is closed, that means its either cancelled or its output has been consumed by the +/// `ProcHandle`. A proc becomes closed when: /// -/// 1. It gets cancelled by `Task::cancel()` or `JoinHandle::cancel()`. -/// 2. Its output is awaited by the `JoinHandle`. +/// 1. It gets cancelled by `LightProc::cancel()` or `ProcHandle::cancel()`. +/// 2. Its output is awaited by the `ProcHandle`. /// 3. It panics while polling the future. -/// 4. It is completed and the `JoinHandle` is dropped. +/// 4. It is completed and the `ProcHandle` is dropped. pub(crate) const CLOSED: usize = 1 << 3; -/// Set if the `JoinHandle` still exists. +/// Set if the `ProcHandle` still exists. /// -/// The `JoinHandle` is a special case in that it is only tracked by this flag, while all other -/// task references (`Task` and `Waker`s) are tracked by the reference count. +/// The `ProcHandle` is a special case in that it is only tracked by this flag, while all other +/// proc references (`LightProc` and `Waker`s) are tracked by the reference count. pub(crate) const HANDLE: usize = 1 << 4; -/// Set if the `JoinHandle` is awaiting the output. +/// Set if the `ProcHandle` is awaiting the output. /// -/// This flag is set while there is a registered awaiter of type `Waker` inside the task. When the -/// task gets closed or completed, we need to wake the awaiter. This flag can be used as a fast -/// check that tells us if we need to wake anyone without acquiring the lock inside the task. +/// This flag is set while there is a registered awaiter of type `Waker` inside the proc. When the +/// proc gets closed or completed, we need to wake the awaiter. This flag can be used as a fast +/// check that tells us if we need to wake anyone without acquiring the lock inside the proc. pub(crate) const AWAITER: usize = 1 << 5; /// Set if the awaiter is locked. @@ -56,10 +56,10 @@ pub(crate) const LOCKED: usize = 1 << 6; /// A single reference. /// -/// The lower bits in the state contain various flags representing the task state, while the upper +/// The lower bits in the state contain various flags representing the proc state, while the upper /// bits contain the reference count. The value of `REFERENCE` represents a single reference in the /// total reference count. /// -/// Note that the reference counter only tracks the `Task` and `Waker`s. The `JoinHandle` is +/// Note that the reference counter only tracks the `LightProc` and `Waker`s. The `ProcHandle` is /// tracked separately by the `HANDLE` flag. pub(crate) const REFERENCE: usize = 1 << 7;