diff --git a/embassy-futures/README.md b/embassy-futures/README.md new file mode 100644 index 00000000..971f4c83 --- /dev/null +++ b/embassy-futures/README.md @@ -0,0 +1,9 @@ +# embassy-futures + +Utilities for working with futures: + +- [`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_all`](select::select_all) - waiting for one future in a list of futures to complete. +- [`yield_now`](yield_now::yield_now) - yielding the current task. diff --git a/embassy-futures/src/lib.rs b/embassy-futures/src/lib.rs index 48c9c857..45bea252 100644 --- a/embassy-futures/src/lib.rs +++ b/embassy-futures/src/lib.rs @@ -1,5 +1,5 @@ #![no_std] -#![doc = include_str!("../../README.md")] +#![doc = include_str!("../README.md")] #![warn(missing_docs)] // This mod MUST go first, so that the others see its macros. diff --git a/embassy-sync/README.md b/embassy-sync/README.md new file mode 100644 index 00000000..106295c0 --- /dev/null +++ b/embassy-sync/README.md @@ -0,0 +1,12 @@ +# embassy-sync + +Synchronization primitives and data structures with an async API: + +- [`Channel`](channel::Channel) - A Multiple Producer Multiple Consumer (MPMC) channel. Each message is only received by a single consumer. +- [`PubSubChannel`](pubsub::PubSubChannel) - A broadcast channel (publish-subscribe) channel. Each message is received by all consumers. +- [`Signal`](signal::Signal) - Signalling latest value to a single consumer. +- [`Mutex`](mutex::Mutex) - A 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. +- [`MultiWakerRegistration`](waitqueue::MultiWakerRegistration) - Utility registering and waking multiple `Waker`'s. diff --git a/embassy-sync/src/lib.rs b/embassy-sync/src/lib.rs index 8e81e5cb..25150e8a 100644 --- a/embassy-sync/src/lib.rs +++ b/embassy-sync/src/lib.rs @@ -1,7 +1,7 @@ #![cfg_attr(not(any(feature = "std", feature = "wasm")), no_std)] #![cfg_attr(feature = "nightly", feature(generic_associated_types, type_alias_impl_trait))] #![allow(clippy::new_without_default)] -#![doc = include_str!("../../README.md")] +#![doc = include_str!("../README.md")] #![warn(missing_docs)] // This mod MUST go first, so that the others see its macros. diff --git a/embassy-sync/src/signal.rs b/embassy-sync/src/signal.rs index 3f665e38..f6ebeb9b 100644 --- a/embassy-sync/src/signal.rs +++ b/embassy-sync/src/signal.rs @@ -6,7 +6,7 @@ use core::task::{Context, Poll, Waker}; /// Single-slot signaling primitive. /// -/// This is similar to a [`Channel`](crate::channel::mpmc::Channel) with a buffer size of 1, except +/// This is similar to a [`Channel`](crate::channel::Channel) with a buffer size of 1, except /// "sending" to it (calling [`Signal::signal`]) when full will overwrite the previous value instead /// of waiting for the receiver to pop the previous value. /// @@ -14,7 +14,7 @@ use core::task::{Context, Poll, Waker}; /// the latest data, and therefore it's fine to "lose" messages. This is often the case for "state" /// updates. /// -/// For more advanced use cases, you might want to use [`Channel`](crate::channel::mpmc::Channel) instead. +/// For more advanced use cases, you might want to use [`Channel`](crate::channel::Channel) instead. /// /// Signals are generally declared as `static`s and then borrowed as required. /// diff --git a/embassy-time/README.md b/embassy-time/README.md new file mode 100644 index 00000000..2be80ff9 --- /dev/null +++ b/embassy-time/README.md @@ -0,0 +1,43 @@ +# embassy-time + +Timekeeping, delays and timeouts. + +Timekeeping is done with elapsed time since system boot. Time is represented in +ticks, where the tick rate is defined by the current driver, usually to match +the tick rate of the hardware. + +Tick counts are 64 bits. At the highest supported tick rate of 1Mhz this supports +representing time spans of up to ~584558 years, which is big enough for all practical +purposes and allows not having to worry about overflows. + +[`Instant`] represents a given instant of time (relative to system boot), and [`Duration`] +represents the duration of a span of time. They implement the math operations you'd expect, +like addition and substraction. + +# Delays and timeouts + +[`Timer`] allows performing async delays. [`Ticker`] allows periodic delays without drifting over time. + +An implementation of the `embedded-hal` delay traits is provided by [`Delay`], for compatibility +with libraries from the ecosystem. + +# Wall-clock time + +The `time` module deals exclusively with a monotonically increasing tick count. +Therefore it has no direct support for wall-clock time ("real life" datetimes +like `2021-08-24 13:33:21`). + +If persistence across reboots is not needed, support can be built on top of +`embassy_time` by storing the offset between "seconds elapsed since boot" +and "seconds since unix epoch". + +# Time driver + +The `time` module is backed by a global "time driver" specified at build time. +Only one driver can be active in a program. + +All methods and structs transparently call into the active driver. This makes it +possible for libraries to use `embassy_time` in a driver-agnostic way without +requiring generic parameters. + +For more details, check the [`driver`] module. diff --git a/embassy-time/src/lib.rs b/embassy-time/src/lib.rs index a6454d55..a6c5d78c 100644 --- a/embassy-time/src/lib.rs +++ b/embassy-time/src/lib.rs @@ -1,50 +1,9 @@ #![cfg_attr(not(any(feature = "std", feature = "wasm")), no_std)] #![cfg_attr(feature = "nightly", feature(generic_associated_types, type_alias_impl_trait))] +#![doc = include_str!("../README.md")] #![allow(clippy::new_without_default)] #![warn(missing_docs)] -//! Timekeeping, delays and timeouts. -//! -//! Timekeeping is done with elapsed time since system boot. Time is represented in -//! ticks, where the tick rate is defined by the current driver, usually to match -//! the tick rate of the hardware. -//! -//! Tick counts are 64 bits. At the highest supported tick rate of 1Mhz this supports -//! representing time spans of up to ~584558 years, which is big enough for all practical -//! purposes and allows not having to worry about overflows. -//! -//! [`Instant`] represents a given instant of time (relative to system boot), and [`Duration`] -//! represents the duration of a span of time. They implement the math operations you'd expect, -//! like addition and substraction. -//! -//! # Delays and timeouts -//! -//! [`Timer`] allows performing async delays. [`Ticker`] allows periodic delays without drifting over time. -//! -//! An implementation of the `embedded-hal` delay traits is provided by [`Delay`], for compatibility -//! with libraries from the ecosystem. -//! -//! # Wall-clock time -//! -//! The `time` module deals exclusively with a monotonically increasing tick count. -//! Therefore it has no direct support for wall-clock time ("real life" datetimes -//! like `2021-08-24 13:33:21`). -//! -//! If persistence across reboots is not needed, support can be built on top of -//! `embassy_time` by storing the offset between "seconds elapsed since boot" -//! and "seconds since unix epoch". -//! -//! # Time driver -//! -//! The `time` module is backed by a global "time driver" specified at build time. -//! Only one driver can be active in a program. -//! -//! All methods and structs transparently call into the active driver. This makes it -//! possible for libraries to use `embassy_time` in a driver-agnostic way without -//! requiring generic parameters. -//! -//! For more details, check the [`driver`] module. - // This mod MUST go first, so that the others see its macros. pub(crate) mod fmt;