2 // due to the usage of `Notify` within the `rt` feature set.
26 /// `Notify` provides a basic mechanism to notify a single task of an event.
27 /// `Notify` itself does not carry any data. Instead, it is to be used to signal
30 /// A `Notify` can be thought of as a [`Semaphore`] starting with 0 permits. The
35 /// The synchronization details of `Notify` are similar to
36 /// [`thread::park`][park] and [`Thread::unpark`][unpark] from std. A [`Notify`]
54 /// use tokio::sync::Notify;
59 ///     let notify = Arc::new(Notify::new());
60 ///     let notify2 = notify.clone();
68 ///     notify.notify_one();
78 /// `notify_one()` will store a permit in the `Notify`, which the following call
82 /// use tokio::sync::Notify;
89 ///     notify: Notify,
97 ///         // Notify the consumer a value is available
98 ///         self.notify.notify_one();
111 ///             self.notify.notified().await;
126 ///     permit to the `Notify`.
133 /// to the `Notify`. This ensures that both futures are woken.
140 /// use tokio::sync::Notify;
147 ///     notify_on_sent: Notify,
195 /// [`notified().await`]: Notify::notified()
196 /// [`notify_one()`]: Notify::notify_one()
200 pub struct Notify {  struct
240 /// Future returned from [`Notify::notified()`].
246     /// The `Notify` being received on.
247     notify: &'a Notify,  field
299 impl Notify {  impl
300     /// Create a new `Notify`, initialized without a permit.
305     /// use tokio::sync::Notify;
307     /// let notify = Notify::new();
309     pub fn new() -> Notify {  in new()
310         Notify {  in new()
316     /// Create a new `Notify`, initialized without a permit.
321     /// use tokio::sync::Notify;
323     /// static NOTIFY: Notify = Notify::const_new();
327     pub const fn const_new() -> Notify {  in const_new()
328         Notify {  in const_new()
342     /// Each `Notify` value holds a single permit. If a permit is available from
355     /// [`notify_one()`]: Notify::notify_one
367     /// use tokio::sync::Notify;
372     ///     let notify = Arc::new(Notify::new());
373     ///     let notify2 = notify.clone();
381     ///     notify.notify_one();
389             notify: self,  in notified()
403     /// permit is stored in this `Notify` value and the **next** call to
407     /// At most one permit may be stored by `Notify`. Many sequential calls to
412     /// [`notified().await`]: Notify::notified()
417     /// use tokio::sync::Notify;
422     ///     let notify = Arc::new(Notify::new());
423     ///     let notify2 = notify.clone();
431     ///     notify.notify_one();
435     #[cfg_attr(docsrs, doc(alias = "notify"))]
457         // There are waiters, the lock must be acquired to notify.  in notify_one()
474     /// `notified().await`. The purpose of this method is to notify all
481     /// use tokio::sync::Notify;
486     ///     let notify = Arc::new(Notify::new());
487     ///     let notify2 = notify.clone();
489     ///     let notified1 = notify.notified();
490     ///     let notified2 = notify.notified();
505         // There are waiters, the lock must be acquired to notify.  in notify_waiters()
564 impl Default for Notify {  implementation
565     fn default() -> Notify {  in default()
566         Notify::new()  in default()
570 impl UnwindSafe for Notify {}  implementation
571 impl RefUnwindSafe for Notify {}  implementation
641     ///     `Notify` was holding a permit from a previous call to `notify_one`.
645     ///     `Notify`, or by a call to `notify_one` or `notify_waiters` that
662     ///     permit to the `Notify`.
669     /// to the `Notify`. This ensures that both futures are woken.
672     /// use tokio::sync::Notify;
679     ///     notify_on_sent: Notify,
725     /// [`notify_one`]: Notify::notify_one()
726     /// [`notify_waiters`]: Notify::notify_waiters()
733     fn project(self: Pin<&mut Self>) -> (&Notify, &mut State, &UnsafeCell<Waiter>) {  in project()  argument
735             // Safety: both `notify` and `state` are `Unpin`.  in project()
737             is_unpin::<&Notify>();  in project()
741             (me.notify, &mut me.state, &me.waiter)  in project()
748         let (notify, state, waiter) = self.project();  in poll_notified()
753                     let curr = notify.state.load(SeqCst);  in poll_notified()
756                     let res = notify.state.compare_exchange(  in poll_notified()
775                     let mut waiters = notify.waiters.lock();  in poll_notified()
778                     let mut curr = notify.state.load(SeqCst);  in poll_notified()
792                                 let res = notify.state.compare_exchange(  in poll_notified()
809                                 let res = notify.state.compare_exchange(  in poll_notified()
851                     // `notify.waiters`). In order to access the waker fields,  in poll_notified()
854                     let waiters = notify.waiters.lock();  in poll_notified()
909         let (notify, state, waiter) = unsafe { Pin::new_unchecked(self).project() };  in drop()
915             let mut waiters = notify.waiters.lock();  in drop()
916             let mut notify_state = notify.state.load(SeqCst);  in drop()
926                 notify.state.store(notify_state, SeqCst);  in drop()
939                 if let Some(waker) = notify_locked(&mut waiters, &notify.state, notify_state) {  in drop()