docs: extend the waker documentation

embassy-sync/README.md

@@ -12,7 +12,7 @@ Synchronization primitives and data structures with async support:
 - [`Mutex`](mutex::Mutex) - Mutex for synchronizing state between asynchronous tasks.
 - [`Pipe`](pipe::Pipe) - Byte stream implementing `embedded_io` traits.
 - [`WakerRegistration`](waitqueue::WakerRegistration) - Utility to register and wake a `Waker`.
-- [`AtomicWaker`](waitqueue::AtomicWaker) - A variant of `WakerRegistration` accessible using a non-mut API.
+- [`AtomicWaker`](waitqueue::AtomicWaker) - Utility to register and wake a `Waker` from interrupt context.
 - [`MultiWakerRegistration`](waitqueue::MultiWakerRegistration) - Utility registering and waking multiple `Waker`'s.
 - [`LazyLock`](lazy_lock::LazyLock) - A value which is initialized on the first access
 

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>>>,
 }

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<()>,
 }

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>,
 }

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>,