futures: readme, docs improvements.

embassy-futures/Cargo.toml

@@ -6,9 +6,12 @@ edition = "2021"
 [package.metadata.embassy_docs]
 src_base = "https://github.com/embassy-rs/embassy/blob/embassy-futures-v$VERSION/embassy-futures/src/"
 src_base_git = "https://github.com/embassy-rs/embassy/blob/$COMMIT/embassy-futures/src/"
-features = ["nightly"]
+features = ["defmt"]
 target = "thumbv7em-none-eabi"
 
+[package.metadata.docs.rs]
+features = ["defmt"]
+
 [dependencies]
 defmt = { version = "0.3", optional = true }
 log = { version = "0.4.14", optional = true }

embassy-futures/README.md

@@ -1,10 +1,28 @@
 # embassy-futures
 
-Utilities for working with futures:
+An [Embassy](https://embassy.dev) project.
+
+Utilities for working with futures, compatible with `no_std` and not using `alloc`. Optimized for code size,
+ideal for embedded systems.
+
+- Future combinators, like [`join`](join) and [`select`](select)
+- Utilities to use `async` without a fully fledged executor: [`block_on`](block_on::block_on) and [`yield_now`](yield_now::yield_now).
+
+## Interoperability
+
+Futures from this crate can run on any executor.
+
+## Minimum supported Rust version (MSRV)
+
+Embassy is guaranteed to compile on the latest stable Rust version at the time of release. It might compile with older versions but that may change in any new patch release.
+
+## License
+
+This work is licensed under either of
+
+- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
+  <http://www.apache.org/licenses/LICENSE-2.0>)
+- MIT license ([LICENSE-MIT](LICENSE-MIT) or <http://opensource.org/licenses/MIT>)
+
+at your option.
 
-- [`select`](select::select) - waiting for one out of two futures to complete.
-- [`select3`](select::select3) - waiting for one out of three futures to complete.
-- [`select4`](select::select4) - waiting for one out of four futures to complete.
-- [`select_array`](select::select_array) - waiting for one future in an array of futures to complete.
-- [`select_slice`](select::select_slice) - waiting for one future in a slice of futures to complete.
-- [`yield_now`](yield_now::yield_now) - yielding the current task.

embassy-futures/src/block_on.rs

@@ -11,6 +11,8 @@ static VTABLE: RawWakerVTable = RawWakerVTable::new(|_| RawWaker::new(ptr::null(
 /// the current thread at 100% cpu usage until the future is done. The
 /// future's `Waker` mechanism is not used.
 ///
+/// You can use this to run multiple futures concurrently with [`join`][crate::join].
+///
 /// It's suitable for systems with no or limited concurrency and without
 /// strict requirements around power consumption. For more complex use
 /// cases, prefer using a "real" executor like `embassy-executor`, which

embassy-futures/src/yield_now.rs

@@ -3,6 +3,23 @@ use core::pin::Pin;
 use core::task::{Context, Poll};
 
 /// Yield from the current task once, allowing other tasks to run.
+///
+/// This can be used to easily and quickly implement simple async primitives
+/// without using wakers. The following snippet will wait for a condition to
+/// hold, while still allowing other tasks to run concurrently (not monopolizing
+/// the executor thread).
+///
+/// ```rust,no_run
+/// while !some_condition() {
+///     yield_now().await;
+/// }
+/// ```
+///
+/// The downside is this will spin in a busy loop, using 100% of the CPU, while
+/// using wakers correctly would allow the CPU to sleep while waiting.
+///
+/// The internal implementation is: on first poll the future wakes itself and
+/// returns `Poll::Pending`. On second poll, it returns `Poll::Ready`.
 pub fn yield_now() -> impl Future<Output = ()> {
     YieldNowFuture { yielded: false }
 }