tokio-rs/tokio
1
0
Fork 0
mirror of https://github.com/tokio-rs/tokio.git synced 2026-08-22 00:00:11 +02:00
Code Issues Packages Projects Releases Wiki Activity

task: fix the incomplete/wrong description of JOIN_WAKER bit. (#5217)

Browse Source 
* task: fix the incomplete/wrong description of JOIN_WAKER bit (#5217)
This commit is contained in:
Abutalib Aghayev
2022-11-24 15:47:15 -05:00
committed by GitHub
parent e316428210
commit 718d6ce8ca
1 changed files with 34 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files
tokio/src/runtime/task/mod.rs
+34 -5
View File
@@ -47,7 +47,8 @@
//!
//! * JOIN_INTEREST - Is set to one if there exists a JoinHandle.
//!
//! * JOIN_WAKER - Is set to one if the JoinHandle has set a waker.
//! * JOIN_WAKER - Acts as an access control bit for the join handle waker. The
//! protocol for its usage is described below.
//!
//! The rest of the bits are used for the ref-count.
//!
@@ -71,10 +72,38 @@
//! a lock for the stage field, and it can be accessed only by the thread
//! that set RUNNING to one.
//!
//! * If JOIN_WAKER is zero, then the JoinHandle has exclusive access to the
//! join handle waker. If JOIN_WAKER and COMPLETE are both one, then the
//! thread that set COMPLETE to one has exclusive access to the join handle
//! waker.
//! * The waker field may be concurrently accessed by different threads: in one
//! thread the runtime may complete a task and *read* the waker field to
//! invoke the waker, and in another thread the task's JoinHandle may be
//! polled, and if the task hasn't yet completed, the JoinHandle may *write*
//! a waker to the waker field. The JOIN_WAKER bit ensures safe access by
//! multiple threads to the waker field using the following rules:
//!
//! 1. JOIN_WAKER is initialized to zero.
//!
//! 2. If JOIN_WAKER is zero, then the JoinHandle has exclusive (mutable)
//! access to the waker field.
//!
//! 3. If JOIN_WAKER is one, then the JoinHandle has shared (read-only)
//! access to the waker field.
//!
//! 4. If JOIN_WAKER is one and COMPLETE is one, then the runtime has shared
//! (read-only) access to the waker field.
//!
//! 5. If the JoinHandle needs to write to the waker field, then the
//! JoinHandle needs to (i) successfully set JOIN_WAKER to zero if it is
//! not already zero to gain exclusive access to the waker field per rule
//! 2, (ii) write a waker, and (iii) successfully set JOIN_WAKER to one.
//!
//! 6. The JoinHandle can change JOIN_WAKER only if COMPLETE is zero (i.e.
//! the task hasn't yet completed).
//!
//! Rule 6 implies that the steps (i) or (iii) of rule 5 may fail due to a
//! race. If step (i) fails, then the attempt to write a waker is aborted. If
//! step (iii) fails because COMPLETE is set to one by another thread after
//! step (i), then the waker field is cleared. Once COMPLETE is one (i.e.
//! task has completed), the JoinHandle will not modify JOIN_WAKER. After the
//! runtime sets COMPLETE to one, it invokes the waker if there is one.
//!
//! All other fields are immutable and can be accessed immutably without
//! synchronization by anyone.