async_hal/
lib.rs

1#![cfg_attr(not(feature = "mock"), no_std)]
2#![cfg_attr(docsrs, feature(doc_cfg))]
3
4//! Async hardware abstraction layer for embedded devices.
5//! This crate provides zero-cost utilities for async IO with `#![no-std]`.
6//!
7//! Two execution models are provided:
8//! - Interrupt mode: Multiple interrupts can each run a future using an [`Executor`].
9//!   Each future is polled on every interrupt and channels can be used to communicate between them.
10//!
11//! - Thread mode: Interrupts wake a main function where a future is being polled with [`block_on`].
12//!
13//! ## Installation
14//!
15//! The easiest way to get started is to enable all features.
16//!
17//! ```toml
18//! [dependencies]
19//! async-hal = { version = "...", features = ["full"] }
20//! ```
21//!
22//! Or by using `cargo add`
23//! ```sh
24//! cargo add async-hal --features full
25//! ```
26//!
27//! ## Feature flags
28//!
29//! Async-hal uses a set of [feature flags] to reduce the amount of compiled code. It
30//! is possible to just enable certain features over others. By default, async-hal
31//! does not enable any features but allows one to enable a subset for their use
32//! case. Below is a list of the available feature flags. You may also notice
33//! above each function, struct and trait there is listed one or more feature flags
34//! that are required for that item to be used. If you are new to async-hal it is
35//! recommended that you use the `full` feature flag which will enable all public APIs.
36//! Beware though that this will pull in many extra dependencies that you may not
37//! need.
38//!
39//! [feature flags]: https://doc.rust-lang.org/cargo/reference/manifest.html#the-features-section
40//!
41//! - `full`: Enables all features listed below except `mock` and `bxcan`.
42//! - `can`: Enables the `async_hal::can` module.
43//! - `delay`: Enables the `async_hal::delay` module.
44//! - `executor`: Enables the `async_hal::executor` module.
45//! - `io`: Enables the `async_hal::io` module.
46//! - `serial`: Enables the `async_hal::serial` module.
47//! - `nb`: Enables async wrappers for non-blocking interfaces (such as from `embedded_hal`).
48//! - `bxcan`: Enables CAN support for stm32 devices with [`bxcan`](https://docs.rs/bxcan/).
49
50use core::task::{Context, Poll};
51use futures::{task::noop_waker, Future, FutureExt};
52
53#[cfg_attr(docsrs, doc(cfg(feature = "can")))]
54#[cfg(feature = "can")]
55/// CAN bus
56pub mod can;
57
58#[cfg_attr(docsrs, doc(cfg(feature = "executor")))]
59#[cfg(feature = "executor")]
60/// Task executor
61pub mod executor;
62#[cfg(feature = "executor")]
63pub use executor::Executor;
64
65/// Interrupt stream
66mod interrupt;
67pub use interrupt::Interrupt;
68
69#[cfg_attr(docsrs, doc(cfg(feature = "io")))]
70#[cfg(feature = "io")]
71/// Asynchronous IO
72pub mod io;
73
74#[cfg_attr(docsrs, doc(cfg(feature = "serial")))]
75#[cfg(feature = "serial")]
76/// Serial port
77pub mod serial;
78
79#[cfg_attr(docsrs, doc(cfg(feature = "delay")))]
80#[cfg(feature = "delay")]
81/// Delay timers
82pub mod delay;
83
84/// Run `future` to completion and return its output.
85/// This will repeatedly poll the future and call `wait()`.
86///
87/// This is useful for microcontrollers that can be set into a low-power mode while waiting,
88/// such as using Cortex-M's `wfi` instruction.
89/// ```
90/// use futures::pin_mut;
91///
92/// let task = async { true };
93/// pin_mut!(task);
94///
95/// let output = async_hal::block_on(task, || {
96///     dbg!("Waiting!");
97/// });
98/// assert!(output);
99/// ```
100pub fn block_on<F, W>(mut future: F, mut wait: W) -> F::Output
101where
102    F: Future + Unpin,
103    W: FnMut(),
104{
105    let waker = noop_waker();
106
107    loop {
108        let mut cx = Context::from_waker(&waker);
109        if let Poll::Ready(output) = future.poll_unpin(&mut cx) {
110            return output;
111        }
112
113        wait()
114    }
115}
async_hal/lib.rs

async_hal/
lib.rs
