From e05f6da2692f2b61986ef2b77789e27d68e4e74a Mon Sep 17 00:00:00 2001
From: Dániel Buga <bugadani@gmail.com>
Date: Fri, 22 Nov 2024 09:21:44 +0100
Subject: Generalize AtomicWaker

---
 embassy-sync/src/waitqueue/atomic_waker.rs | 42 +++++++++++++++++++++++-------
 1 file changed, 32 insertions(+), 10 deletions(-)

(limited to 'embassy-sync/src/waitqueue')

diff --git a/embassy-sync/src/waitqueue/atomic_waker.rs b/embassy-sync/src/waitqueue/atomic_waker.rs
index 63fe04a6e..231902c5a 100644
--- a/embassy-sync/src/waitqueue/atomic_waker.rs
+++ b/embassy-sync/src/waitqueue/atomic_waker.rs
@@ -1,26 +1,25 @@
 use core::cell::Cell;
 use core::task::Waker;
 
-use crate::blocking_mutex::raw::CriticalSectionRawMutex;
+use crate::blocking_mutex::raw::{CriticalSectionRawMutex, RawMutex};
 use crate::blocking_mutex::Mutex;
 
 /// Utility struct to register and wake a waker.
-pub struct AtomicWaker {
-    waker: Mutex<CriticalSectionRawMutex, Cell<Option<Waker>>>,
+pub struct GenericAtomicWaker<M: RawMutex> {
+    waker: Mutex<M, Cell<Option<Waker>>>,
 }
 
-impl AtomicWaker {
+impl<M: RawMutex> GenericAtomicWaker<M> {
     /// Create a new `AtomicWaker`.
-    pub const fn new() -> Self {
+    pub const fn new(mutex: M) -> Self {
         Self {
-            waker: Mutex::const_new(CriticalSectionRawMutex::new(), Cell::new(None)),
+            waker: Mutex::const_new(mutex, Cell::new(None)),
         }
     }
 
     /// Register a waker. Overwrites the previous waker, if any.
     pub fn register(&self, w: &Waker) {
-        critical_section::with(|cs| {
-            let cell = self.waker.borrow(cs);
+        self.waker.lock(|cell| {
             cell.set(match cell.replace(None) {
                 Some(w2) if (w2.will_wake(w)) => Some(w2),
                 _ => Some(w.clone()),
@@ -30,8 +29,7 @@ impl AtomicWaker {
 
     /// Wake the registered waker, if any.
     pub fn wake(&self) {
-        critical_section::with(|cs| {
-            let cell = self.waker.borrow(cs);
+        self.waker.lock(|cell| {
             if let Some(w) = cell.replace(None) {
                 w.wake_by_ref();
                 cell.set(Some(w));
@@ -39,3 +37,27 @@ impl AtomicWaker {
         })
     }
 }
+
+/// Utility struct to register and wake a waker.
+pub struct AtomicWaker {
+    waker: GenericAtomicWaker<CriticalSectionRawMutex>,
+}
+
+impl AtomicWaker {
+    /// Create a new `AtomicWaker`.
+    pub const fn new() -> Self {
+        Self {
+            waker: GenericAtomicWaker::new(CriticalSectionRawMutex::new()),
+        }
+    }
+
+    /// Register a waker. Overwrites the previous waker, if any.
+    pub fn register(&self, w: &Waker) {
+        self.waker.register(w);
+    }
+
+    /// Wake the registered waker, if any.
+    pub fn wake(&self) {
+        self.waker.wake();
+    }
+}
-- 
cgit 


From c2173591aa77ab7aa0a1b3d921883667fb9881f4 Mon Sep 17 00:00:00 2001
From: ckrenslehner <ckrenslehner@gmail.com>
Date: Sat, 26 Apr 2025 20:07:30 +0200
Subject: docs: extend the waker documentation

---
 embassy-sync/src/waitqueue/atomic_waker.rs       | 3 +++
 embassy-sync/src/waitqueue/atomic_waker_turbo.rs | 3 +++
 embassy-sync/src/waitqueue/multi_waker.rs        | 2 ++
 embassy-sync/src/waitqueue/waker_registration.rs | 4 ++++
 4 files changed, 12 insertions(+)

(limited to 'embassy-sync/src/waitqueue')

diff --git a/embassy-sync/src/waitqueue/atomic_waker.rs b/embassy-sync/src/waitqueue/atomic_waker.rs
index 231902c5a..5a9910e7f 100644
--- a/embassy-sync/src/waitqueue/atomic_waker.rs
+++ b/embassy-sync/src/waitqueue/atomic_waker.rs
@@ -5,6 +5,9 @@ use crate::blocking_mutex::raw::{CriticalSectionRawMutex, RawMutex};
 use crate::blocking_mutex::Mutex;
 
 /// Utility struct to register and wake a waker.
+/// If a waker is registered, registering another waker will replace the previous one without waking it.
+/// Intended to wake a task from an interrupt. Therefore, it is generally not expected,
+/// that multiple tasks register try to register a waker simultaneously.
 pub struct GenericAtomicWaker<M: RawMutex> {
     waker: Mutex<M, Cell<Option<Waker>>>,
 }
diff --git a/embassy-sync/src/waitqueue/atomic_waker_turbo.rs b/embassy-sync/src/waitqueue/atomic_waker_turbo.rs
index 5c6a96ec8..c06b83056 100644
--- a/embassy-sync/src/waitqueue/atomic_waker_turbo.rs
+++ b/embassy-sync/src/waitqueue/atomic_waker_turbo.rs
@@ -4,6 +4,9 @@ use core::sync::atomic::{AtomicPtr, Ordering};
 use core::task::Waker;
 
 /// Utility struct to register and wake a waker.
+/// If a waker is registered, registering another waker will replace the previous one without waking it.
+/// The intended use case is to wake tasks from interrupts. Therefore, it is generally not expected,
+/// that multiple tasks register try to register a waker simultaneously.
 pub struct AtomicWaker {
     waker: AtomicPtr<()>,
 }
diff --git a/embassy-sync/src/waitqueue/multi_waker.rs b/embassy-sync/src/waitqueue/multi_waker.rs
index 0e520bf40..0384d6bed 100644
--- a/embassy-sync/src/waitqueue/multi_waker.rs
+++ b/embassy-sync/src/waitqueue/multi_waker.rs
@@ -3,6 +3,8 @@ use core::task::Waker;
 use heapless::Vec;
 
 /// Utility struct to register and wake multiple wakers.
+/// Queue of wakers with a maximum length of `N`.
+/// Intended for waking multiple tasks.
 pub struct MultiWakerRegistration<const N: usize> {
     wakers: Vec<Waker, N>,
 }
diff --git a/embassy-sync/src/waitqueue/waker_registration.rs b/embassy-sync/src/waitqueue/waker_registration.rs
index 9b666e7c4..7f24f8fb6 100644
--- a/embassy-sync/src/waitqueue/waker_registration.rs
+++ b/embassy-sync/src/waitqueue/waker_registration.rs
@@ -2,6 +2,10 @@ use core::mem;
 use core::task::Waker;
 
 /// Utility struct to register and wake a waker.
+/// If a waker is registered, registering another waker will replace the previous one.
+/// The previous waker will be woken in this case, giving it a chance to reregister itself.
+/// Although it is possible to wake multiple tasks this way,
+/// this will cause them to wake each other in a loop registering themselves.
 #[derive(Debug, Default)]
 pub struct WakerRegistration {
     waker: Option<Waker>,
-- 
cgit