zephyr: mark old async methods as deprecated

This work-queue based async executor, although functional, has some
significant problems. Most notably, it doesn't use wakers, and as such,
is incompatible with other utilities that have been written to be used
with Async.  Trying to combine them will, in fact, result in undefined
behavior.

Now that the embassy-based executor-zephyr is in main, mark these as
deprecated so that code can gradually move to newer solutions.

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

Author: d3zd3z

zephyr/src/kio.rs

@@ -20,12 +20,15 @@ use crate::work::{futures::JoinHandle, futures::WorkBuilder, WorkQueue};
 
 pub mod sync;
 
+#[allow(deprecated)]
 pub use crate::work::futures::sleep;
 
 /// Run an async future on the given worker thread.
 ///
 /// Arrange to have the given future run on the given worker thread.  The resulting `JoinHandle` has
 /// `join` and `join_async` methods that can be used to wait for the given thread.
+#[deprecated(since = "0.1.0",
+             note = "Prefer the executor-zephyr")]
 pub fn spawn<F>(future: F, worker: &WorkQueue, name: &'static CStr) -> JoinHandle<F>
 where
     F: Future + Send + 'static,
@@ -54,6 +57,8 @@ where
 ///
 /// # Panics
 /// If this is called other than from a worker task running on a work thread, it will panic.
+#[deprecated(since = "0.1.0",
+             note = "Prefer the executor-zephyr")]
 pub fn spawn_local<F>(future: F, name: &'static CStr) -> JoinHandle<F>
 where
     F: Future + 'static,
@@ -64,6 +69,8 @@ where
 
 /// Yield the current thread, returning it to the work queue to be run after other work on that
 /// queue.  (This has to be called `yield_now` in Rust, because `yield` is a keyword.)
+#[deprecated(since = "0.1.0",
+             note = "Prefer the executor-zephyr")]
 pub fn yield_now() -> impl Future<Output = ()> {
     YieldNow { waited: false }
 }

zephyr/src/kio/sync.rs

@@ -31,6 +31,8 @@ use crate::{
 /// A mutual exclusion primitive useful for protecting shared data.  Async version.
 ///
 /// This mutex will block a task waiting for the lock to become available.
+#[deprecated(since = "0.1.0",
+             note = "Prefer the executor-zephyr")]
 pub struct Mutex<T: ?Sized> {
     /// The semaphore indicating ownership of the data.  When it is "0" the task that did the 'take'
     /// on it owns the data, and will use `give` when it is unlocked.  This mechanism works for
@@ -40,16 +42,20 @@ pub struct Mutex<T: ?Sized> {
 }
 
 // SAFETY: The semaphore, with the semantics provided here, provide Send and Sync.
+#[allow(deprecated)]
 unsafe impl<T: ?Sized + Send> Send for Mutex<T> {}
+#[allow(deprecated)]
 unsafe impl<T: ?Sized + Send> Sync for Mutex<T> {}
 
+#[allow(deprecated)]
 impl<T> fmt::Debug for Mutex<T> {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         write!(f, "Mutex {:?}", self.inner)
     }
 }
 
 /// An RAII implementation of a held lock.
+#[allow(deprecated)]
 pub struct MutexGuard<'a, T: ?Sized + 'a> {
     lock: &'a Mutex<T>,
     // Mark !Send explicitly until support is added to Rust for this.
@@ -58,6 +64,7 @@ pub struct MutexGuard<'a, T: ?Sized + 'a> {
 
 unsafe impl<T: ?Sized + Sync> Sync for MutexGuard<'_, T> {}
 
+#[allow(deprecated)]
 impl<T> Mutex<T> {
     /// Construct a new Mutex.
     pub fn new(t: T) -> Mutex<T> {
@@ -68,6 +75,7 @@ impl<T> Mutex<T> {
     }
 }
 
+#[allow(deprecated)]
 impl<T: ?Sized> Mutex<T> {
     /// Acquire the mutex, blocking the current thread until it is able to do so.
     ///
@@ -94,6 +102,7 @@ impl<T: ?Sized> Mutex<T> {
     }
 }
 
+#[allow(deprecated)]
 impl<'mutex, T: ?Sized> MutexGuard<'mutex, T> {
     unsafe fn new(lock: &'mutex Mutex<T>) -> MutexGuard<'mutex, T> {
         MutexGuard {
@@ -103,6 +112,7 @@ impl<'mutex, T: ?Sized> MutexGuard<'mutex, T> {
     }
 }
 
+#[allow(deprecated)]
 impl<T: ?Sized> Deref for MutexGuard<'_, T> {
     type Target = T;
 
@@ -111,12 +121,14 @@ impl<T: ?Sized> Deref for MutexGuard<'_, T> {
     }
 }
 
+#[allow(deprecated)]
 impl<T: ?Sized> DerefMut for MutexGuard<'_, T> {
     fn deref_mut(&mut self) -> &mut T {
         unsafe { &mut *self.lock.data.get() }
     }
 }
 
+#[allow(deprecated)]
 impl<T: ?Sized> Drop for MutexGuard<'_, T> {
     #[inline]
     fn drop(&mut self) {

zephyr/src/sync/channel.rs

@@ -215,6 +215,8 @@ impl<T: Unpin> Sender<T> {
     /// This has the same behavior as [`send_timeout`], but as an Async function.
     ///
     /// [`send_timeout`]: Sender::send_timeout
+    #[deprecated(since = "0.1.0",
+                 note = "Prefer the executor-zephyr")]
     pub fn send_timeout_async<'a>(
         &'a self,
         msg: T,
@@ -229,6 +231,9 @@ impl<T: Unpin> Sender<T> {
     }
 
     /// Sends a message over the given channel, waiting if necessary. Async version.
+    #[deprecated(since = "0.1.0",
+                 note = "Prefer the executor-zephyr")]
+    #[allow(deprecated)]
     pub async fn send_async(&self, msg: T) -> Result<(), SendError<T>> {
         self.send_timeout_async(msg, Forever).await
     }
@@ -424,6 +429,8 @@ impl<T> Receiver<T> {
 }
 
 // Note that receive doesn't need the Unpin constraint, as we aren't storing any message.
+#[deprecated(since = "0.1.0",
+             note = "Prefer the executor-zephyr")]
 impl<T> Receiver<T> {
     /// Waits for a message to be received from the channel, but only for a limited time.
     /// Async version.
@@ -526,6 +533,7 @@ impl<'a, T> Future for RecvFuture<'a, T> {
         }
 
         // Otherwise, schedule to wakeup on receipt or timeout.
+        #[allow(deprecated)]
         cx.add_queue(self.receiver.as_queue(), self.timeout);
         self.waited = true;
 
@@ -662,6 +670,7 @@ where
     // Start with a deadline 'period' out in the future.
     let mut next = crate::time::now() + period;
     loop {
+        #[allow(deprecated)]
         if let Ok(ev) = events.recv_timeout_async(next).await {
             handle(Some(ev)).await;
             continue;

zephyr/src/sys/sync/semaphore.rs

@@ -82,6 +82,8 @@ impl Semaphore {
     ///
     /// Returns a future that either waits for the semaphore, or returns status.
     #[cfg(CONFIG_RUST_ALLOC)]
+    #[deprecated(since = "0.1.0",
+                 note = "Prefer the executor-zephyr")]
     pub fn take_async<'a>(
         &'a self,
         timeout: impl Into<Timeout>,

zephyr/src/work/futures.rs

@@ -104,6 +104,7 @@ impl<T> Answer<T> {
 
     /// Asynchronously wait for an answer.
     pub async fn take_async(&self) -> T {
+        #[allow(deprecated)]
         self.wake
             .take_async(Forever)
             .await
@@ -587,6 +588,8 @@ unsafe fn void_drop(_: *const ()) {}
 type EventArray = ArrayVec<UnsafeCell<k_poll_event>, 1>;
 
 /// Async sleep.
+#[deprecated(since = "0.1.0",
+             note = "Prefer the executor-zephyr")]
 pub fn sleep(duration: Duration) -> Sleep {
     Sleep {
         ticks_left: duration.ticks(),