embedded_executor/
lib.rs

1//! # Embedded Futures Executor
2//!
3//! This crate provides a futures executor whose only dependency is `alloc`.
4//!
5//! ## Dependency Setup
6//!
7//! To make https://docs.rs/ happy, this crate uses `std` by default. For use
8//! on embedded systems, disable default features and enable the `alloc` feature:
9//!
10//! ```toml
11//! [dependencies.embedded-executor]
12//! version = "0.2.2"
13//! default-features = false
14//! features = ["alloc"]
15//! ```
16//!
17//! ## The Executor
18//!
19//! The base executor type is [`AllocExecutor`]. To use it, you need both a
20//! [`RawMutex`] implementation and a [`Sleep`] implementation.
21//!
22//! For convenience, [`SpinSleep`] provides a simple spinlock-based [`Sleep`]
23//! implementation, and an example spinlock [`RawMutex`] can be found in the
24//! [`lock_api`] docs. It is recommended, however, to use implementations more
25//! suited to your particular platform, such as a `Sleep` that calls
26//! [`cortex_m::asm::wfi`] and a `RawMutex` that disables/enables interrupts.
27//!
28//! [`RawMutex`]: https://docs.rs/lock_api/0.1.5/lock_api/trait.RawMutex.html
29//! [`lock_api`]: https://docs.rs/lock_api/0.1.5/lock_api/
30//! [`cortex_m::asm::wfi`]: https://docs.rs/cortex-m/0.5.8/cortex_m/asm/fn.wfi.html
31//!
32//! Once you have all of these pieces, it's usually easiest to create an alias for
33//! your platform-specific executor:
34//!
35//! ```rust,ignore
36//! type Executor<'a> = AllocExecutor<'a, IFreeMutex, WFISleep>;
37//! ```
38//!
39//! which can then be instantiated via its `new` or `with_capacity` methods.
40//!
41//! ## Spawning
42//!
43//! Futures can be spawned either by calling [`AllocExecutor::spawn`] or by
44//! getting a [`alloc_executor::Spawner`] and calling
45//! [`alloc_executor::Spawner::spawn`]. The `Spawner` can also be passed to
46//! other `Futures` for even more spawning goodness.
47//!
48//! ## Running
49//!
50//! Running the executor is done via the [`AllocExecutor::run`] method. This
51//! will drive all spawned futures and any new futures that get spawned to
52//! completion before returning.
53
54#![recursion_limit = "128"]
55#![cfg_attr(all(not(test), not(feature = "std")), no_std)]
56#![warn(missing_docs)]
57
58extern crate alloc;
59
60mod sleep;
61pub use self::sleep::*;
62
63#[cfg(any(feature = "alloc", feature = "std"))]
64pub mod alloc_executor;
65#[cfg(any(feature = "alloc", feature = "std"))]
66pub use self::alloc_executor::inner::AllocExecutor;
67
68#[cfg(any(feature = "alloc", feature = "std"))]
69mod future_box;
70
71mod wake;
72pub use self::wake::*;