zephyr: Add sync::Condvar

Add the high-level `sync::Condvar` to go along with `sync::Mutex` for
thread synchronization.

Signed-off-by: David Brown <[email protected]>

Author: d3zd3z

zephyr/src/sync.rs

@@ -145,3 +145,74 @@ impl<T: ?Sized> Drop for MutexGuard<'_, T> {
         self.lock.inner.unlock().unwrap();
     }
 }
+
+/// Inspired by
+/// [`std::sync::Condvar`](https://doc.rust-lang.org/stable/std/sync/struct.Condvar.html),
+/// implemented directly using `z_condvar` in Zephyr.
+///
+/// Condition variables represent the ability to block a thread such that it consumes no CPU time
+/// while waiting for an even to occur.  Condition variables are typically associated with a
+/// boolean predicate (a condition) and a mutex.  The predicate is always verified inside of the
+/// mutex before determining that a thread must block.
+///
+/// Functions in this module will block the current **thread** of execution.  Note that any attempt
+/// to use multiple mutexces on the same condition variable may result in a runtime panic.
+pub struct Condvar {
+    inner: sys::Condvar,
+}
+
+impl Condvar {
+    /// Construct a new wrapped Condvar, using the given underlying `k_condvar`.
+    ///
+    /// This is different from `std::sync::Condvar` in that in Zephyr, objects are frequently
+    /// allocated statically, and the sys Condvar will be taken by this structure.
+    pub const fn new_from(raw_condvar: sys::Condvar) -> Condvar {
+        Condvar { inner: raw_condvar }
+    }
+
+    /// Blocks the current thread until this conditional variable receives a notification.
+    ///
+    /// This function will automatically unlock the mutex specified (represented by `guard`) and
+    /// block the current thread.  This means that any calls to `notify_one` or `notify_all` which
+    /// happen logically after the mutex is unlocked are candidates to wake this thread up.  When
+    /// this function call returns, the lock specified will have been re-equired.
+    ///
+    /// Note that this function is susceptable to spurious wakeups.  Condition variables normally
+    /// have a boolean predicate associated with them, and the predicate must always be checked
+    /// each time this function returns to protect against spurious wakeups.
+    pub fn wait<'a, T>(&self, guard: MutexGuard<'a, T>) -> LockResult<MutexGuard<'a, T>> {
+        self.inner.wait(&guard.lock.inner);
+        Ok(guard)
+    }
+
+    // TODO: wait_while
+    // TODO: wait_timeout_ms
+    // TODO: wait_timeout
+    // TODO: wait_timeout_while
+
+    /// Wakes up one blocked thread on this condvar.
+    ///
+    /// If there is a blocked thread on this condition variable, then it will be woken up from its
+    /// call to `wait` or `wait_timeout`. Calls to `notify_one` are not buffered in any way.
+    ///
+    /// To wakeup all threads, see `notify_all`.
+    pub fn notify_one(&self) {
+        self.inner.notify_one();
+    }
+
+    /// Wakes up all blocked threads on this condvar.
+    ///
+    /// This methods will ensure that any current waiters on the condition variable are awoken.
+    /// Calls to `notify_all()` are not buffered in any way.
+    ///
+    /// To wake up only one thread, see `notify_one`.
+    pub fn notify_all(&self) {
+        self.inner.notify_all();
+    }
+}
+
+impl fmt::Debug for Condvar {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "Condvar {:?}", self.inner)
+    }
+}