diff --git a/tokio/src/runtime/task/mod.rs b/tokio/src/runtime/task/mod.rs index cfcf6f7d49e..f9202030019 100644 --- a/tokio/src/runtime/task/mod.rs +++ b/tokio/src/runtime/task/mod.rs @@ -98,17 +98,26 @@ //! to clear the waker field, only steps (i) and (ii) are relevant. //! //! 6. The `JoinHandle` can change `JOIN_WAKER` only if COMPLETE is zero (i.e. -//! the task hasn't yet completed). +//! the task hasn't yet completed). The runtime can change `JOIN_WAKER` only +//! if COMPLETE is one. //! //! 7. If `JOIN_INTEREST` is zero and COMPLETE is one, then the runtime has -//! exclusive (mutable) access to the waker field. +//! exclusive (mutable) access to the waker field. This might happen if the +//! `JoinHandle` gets dropped right after the task completes and the runtime +//! sets the `COMPLETE` bit. In this case the runtime needs the mutable access +//! to the waker field to drop it. //! //! 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. +//! runtime sets COMPLETE to one, it invokes the waker if there is one so in this +//! case when a task completes the `JOIN_WAKER` bit implicates to the runtime +//! wether it should invoket he waker or not. After the runtime is done with using +//! the waker during task completion, it unsets the `JOIN_WAKER` bit to give the +//! `JoinHandle` exclusive access again so that it is able to drop the waker at a +//! later point. //! //! All other fields are immutable and can be accessed immutably without //! synchronization by anyone.