Merge #278

278: [Reorganization Proposal 1] Move traits into blocking/nonblocking modules r=therealprof a=eldruin As discussed in our weekly meeting. I chose `nonblocking` as module name because `nb` could be misunderstood as a re-exported `nb` crate. An alternative is #279 Co-authored-by: Diego Barrios Romero <[email protected]>
rust-embedded · May 19, 2021 · b60c39a · b60c39a
2 parents e835410 + 4f60777
commit b60c39a
Show file tree

Hide file tree

Showing 18 changed files with 82 additions and 62 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -14,6 +14,9 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 ### Changed
 - Swap PWM channel arguments to references
 - All trait methods have been renamed to remove the `try_` prefix (i.e. `try_send` -> `send`) for consistency.
+- Moved all traits into two modules depending on the execution model: `blocking` and `nb` (non-blocking).
+- Re-export `nb::{block!, Error, Result}` to avoid version mismatches. These should be used instead of
+  importing the `nb` crate directly in dependendent crates.
 
 ## [v1.0.0-alpha.4] - 2020-11-11
 

diff --git a/src/digital.rs → src/blocking/digital.rs b/src/digital.rs → src/blocking/digital.rs
@@ -7,7 +7,7 @@ use core::{convert::From, ops::Not};
 /// Conversion from `bool` and logical negation are also implemented
 /// for this type.
 /// ```rust
-/// # use embedded_hal::digital::PinState;
+/// # use embedded_hal::blocking::digital::PinState;
 /// let state = PinState::from(false);
 /// assert_eq!(state, PinState::Low);
 /// assert_eq!(!state, PinState::High);
@@ -100,8 +100,8 @@ pub trait ToggleableOutputPin {
 /// toggleable by software.
 ///
 /// ```
-/// use embedded_hal::digital::{OutputPin, StatefulOutputPin, ToggleableOutputPin};
-/// use embedded_hal::digital::toggleable;
+/// use embedded_hal::blocking::digital::{OutputPin, StatefulOutputPin, ToggleableOutputPin};
+/// use embedded_hal::blocking::digital::toggleable;
 /// use core::convert::Infallible;
 ///
 /// /// A virtual output pin that exists purely in software
@@ -182,7 +182,7 @@ pub trait InputPin {
 ///
 /// ```
 /// use core::time::Duration;
-/// use embedded_hal::digital::{IoPin, InputPin, OutputPin};
+/// use embedded_hal::blocking::digital::{IoPin, InputPin, OutputPin};
 ///
 /// pub fn ping_and_read<TInputPin, TOutputPin, TError>(
 ///     mut pin: TOutputPin, delay_fn: &dyn Fn(Duration) -> ()) -> Result<bool, TError>

diff --git a/src/blocking/mod.rs b/src/blocking/mod.rs
@@ -5,7 +5,11 @@
 //! Implementing that marker trait will opt in your type into a blanket implementation.
 
 pub mod delay;
+pub mod digital;
 pub mod i2c;
+pub mod pwm;
+pub mod qei;
 pub mod rng;
 pub mod serial;
 pub mod spi;
+pub mod watchdog;
diff --git a/src/pwm.rs → src/blocking/pwm.rs b/src/pwm.rs → src/blocking/pwm.rs
@@ -34,7 +34,7 @@
 /// # impl U32Ext for u32 { fn khz(self) -> KiloHertz { KiloHertz(self) } }
 /// # enum Channel { _1, _2 }
 /// # struct Pwm1;
-/// # impl hal::pwm::Pwm for Pwm1 {
+/// # impl hal::blocking::pwm::Pwm for Pwm1 {
 /// #     type Error = Infallible;
 /// #     type Channel = Channel;
 /// #     type Time = KiloHertz;

diff --git a/src/qei.rs → src/blocking/qei.rs b/src/qei.rs → src/blocking/qei.rs
@@ -38,14 +38,14 @@
 /// # trait U32Ext { fn s(self) -> Seconds; }
 /// # impl U32Ext for u32 { fn s(self) -> Seconds { Seconds(self) } }
 /// # struct Qei1;
-/// # impl hal::qei::Qei for Qei1 {
+/// # impl hal::blocking::qei::Qei for Qei1 {
 /// #     type Error = Infallible;
 /// #     type Count = u16;
 /// #     fn count(&self) -> Result<u16, Self::Error> { Ok(0) }
-/// #     fn direction(&self) -> Result<::hal::qei::Direction, Self::Error> { unimplemented!() }
+/// #     fn direction(&self) -> Result<::hal::blocking::qei::Direction, Self::Error> { unimplemented!() }
 /// # }
 /// # struct Timer6;
-/// # impl hal::timer::CountDown for Timer6 {
+/// # impl hal::nb::timer::CountDown for Timer6 {
 /// #     type Error = Infallible;
 /// #     type Time = Seconds;
 /// #     fn start<T>(&mut self, _: T) -> Result<(), Infallible> where T: Into<Seconds> { Ok(()) }

diff --git a/src/blocking/serial.rs b/src/blocking/serial.rs
@@ -23,13 +23,13 @@ pub trait Write<Word> {
 pub mod write {
     /// Marker trait to opt into default blocking write implementation
     ///
-    /// Implementers of [`serial::Write`] can implement this marker trait
+    /// Implementers of [`nonblocking::serial::Write`] can implement this marker trait
     /// for their type. Doing so will automatically provide the default
     /// implementation of [`blocking::serial::Write`] for the type.
     ///
-    /// [`serial::Write`]: ../../serial/trait.Write.html
+    /// [`nonblocking::serial::Write`]: ../../nonblocking/serial/trait.Write.html
     /// [`blocking::serial::Write`]: ../trait.Write.html
-    pub trait Default<Word>: crate::serial::Write<Word> {}
+    pub trait Default<Word>: crate::nb::serial::Write<Word> {}
 
     impl<S, Word> crate::blocking::serial::Write<Word> for S
     where

diff --git a/src/blocking/spi.rs b/src/blocking/spi.rs
@@ -32,8 +32,8 @@ pub trait WriteIter<W> {
 /// Blocking transfer
 pub mod transfer {
     /// Default implementation of `blocking::spi::Transfer<W>` for implementers of
-    /// `spi::FullDuplex<W>`
-    pub trait Default<W>: crate::spi::FullDuplex<W> {}
+    /// `nonblocking::spi::FullDuplex<W>`
+    pub trait Default<W>: crate::nb::spi::FullDuplex<W> {}
 
     impl<W, S> crate::blocking::spi::Transfer<W> for S
     where
@@ -55,8 +55,9 @@ pub mod transfer {
 
 /// Blocking write
 pub mod write {
-    /// Default implementation of `blocking::spi::Write<W>` for implementers of `spi::FullDuplex<W>`
-    pub trait Default<W>: crate::spi::FullDuplex<W> {}
+    /// Default implementation of `blocking::spi::Write<W>` for implementers
+    /// of `nonblocking::spi::FullDuplex<W>`
+    pub trait Default<W>: crate::nb::spi::FullDuplex<W> {}
 
     impl<W, S> crate::blocking::spi::Write<W> for S
     where
@@ -79,8 +80,8 @@ pub mod write {
 /// Blocking write (iterator version)
 pub mod write_iter {
     /// Default implementation of `blocking::spi::WriteIter<W>` for implementers of
-    /// `spi::FullDuplex<W>`
-    pub trait Default<W>: crate::spi::FullDuplex<W> {}
+    /// `nonblocking::spi::FullDuplex<W>`
+    pub trait Default<W>: crate::nb::spi::FullDuplex<W> {}
 
     impl<W, S> crate::blocking::spi::WriteIter<W> for S
     where

diff --git a/src/watchdog.rs → src/blocking/watchdog.rs b/src/watchdog.rs → src/blocking/watchdog.rs
diff --git a/src/fmt.rs b/src/fmt.rs
@@ -3,7 +3,7 @@
 //! TODO write example of usage
 use core::fmt::{Result, Write};
 
-impl<Word, Error> Write for dyn crate::serial::Write<Word, Error = Error> + '_
+impl<Word, Error> Write for dyn crate::nb::serial::Write<Word, Error = Error> + '_
 where
     Word: From<u8>,
 {

diff --git a/src/lib.rs b/src/lib.rs
@@ -145,7 +145,7 @@
 //!     // omitted: other error variants
 //! }
 //!
-//! impl hal::serial::Read<u8> for Serial<USART1> {
+//! impl hal::nb::serial::Read<u8> for Serial<USART1> {
 //!     type Error = Error;
 //!
 //!     fn read(&mut self) -> nb::Result<u8, Error> {
@@ -167,7 +167,7 @@
 //!     }
 //! }
 //!
-//! impl hal::serial::Write<u8> for Serial<USART1> {
+//! impl hal::nb::serial::Write<u8> for Serial<USART1> {
 //!     type Error = Error;
 //!
 //!     fn write(&mut self, byte: u8) -> nb::Result<(), Error> {
@@ -198,7 +198,7 @@
 //!
 //! ```
 //! use crate::stm32f1xx_hal::Serial1;
-//! use embedded_hal::serial::Write;
+//! use embedded_hal::nb::serial::Write;
 //! use nb::block;
 //!
 //! # fn main() {
@@ -248,7 +248,7 @@
 //!
 //! fn write_all<S>(serial: &mut S, buffer: &[u8]) -> Result<(), S::Error>
 //! where
-//!     S: hal::serial::Write<u8>
+//!     S: hal::nb::serial::Write<u8>
 //! {
 //!     for &byte in buffer {
 //!         block!(serial.write(byte))?;
@@ -281,8 +281,8 @@
 //!     timeout: T::Time,
 //! ) -> Result<u8, Error<S::Error, T::Error>>
 //! where
-//!     T: hal::timer::CountDown<Error = ()>,
-//!     S: hal::serial::Read<u8>,
+//!     T: hal::nb::timer::CountDown<Error = ()>,
+//!     S: hal::nb::serial::Read<u8>,
 //! {
 //!     timer.start(timeout).map_err(Error::TimedOut)?;
 //!
@@ -325,7 +325,7 @@
 //!
 //! fn flush<S>(serial: &mut S, cb: &mut CircularBuffer)
 //! where
-//!     S: hal::serial::Write<u8, Error = Infallible>,
+//!     S: hal::nb::serial::Write<u8, Error = Infallible>,
 //! {
 //!     loop {
 //!         if let Some(byte) = cb.peek() {
@@ -389,7 +389,7 @@
 //! #     fn deref_mut(&mut self) -> &mut T { self.0 }
 //! # }
 //! # struct Serial1;
-//! # impl hal::serial::Write<u8> for Serial1 {
+//! # impl hal::nb::serial::Write<u8> for Serial1 {
 //! #   type Error = Infallible;
 //! #   fn write(&mut self, _: u8) -> nb::Result<(), Infallible> { Err(::nb::Error::WouldBlock) }
 //! #   fn flush(&mut self) -> nb::Result<(), Infallible> { Err(::nb::Error::WouldBlock) }
@@ -408,19 +408,10 @@
 #![deny(missing_docs)]
 #![no_std]
 
-pub mod adc;
 pub mod blocking;
-pub mod capture;
-pub mod digital;
 pub mod fmt;
+pub mod nb;
 pub mod prelude;
-pub mod pwm;
-pub mod qei;
-pub mod rng;
-pub mod serial;
-pub mod spi;
-pub mod timer;
-pub mod watchdog;
 
 mod private {
     use crate::blocking::i2c::{SevenBitAddress, TenBitAddress};

diff --git a/src/adc.rs → src/nb/adc.rs b/src/adc.rs → src/nb/adc.rs
@@ -8,7 +8,7 @@
 ///
 /// ```
 /// # use core::marker::PhantomData;
-/// # use embedded_hal::adc::Channel;
+/// # use embedded_hal::nb::adc::Channel;
 ///
 /// struct Adc1; // Example ADC with single bank of 8 channels
 /// struct Gpio1Pin1<MODE>(PhantomData<MODE>);
@@ -55,7 +55,7 @@ pub trait Channel<ADC> {
 /// of the request (in contrast to continuous asynchronous sampling).
 ///
 /// ```
-/// use embedded_hal::adc::{Channel, OneShot};
+/// use embedded_hal::nb::adc::{Channel, OneShot};
 ///
 /// struct MyAdc; // 10-bit ADC, with 5 channels
 /// # impl MyAdc {

diff --git a/src/capture.rs → src/nb/capture.rs b/src/capture.rs → src/nb/capture.rs
@@ -36,7 +36,7 @@
 /// # impl U32Ext for u32 { fn ms(self) -> MilliSeconds { MilliSeconds(self) } }
 /// # struct Capture1;
 /// # enum Channel { _1 }
-/// # impl hal::capture::Capture for Capture1 {
+/// # impl hal::nb::capture::Capture for Capture1 {
 /// #     type Error = Infallible;
 /// #     type Capture = u16;
 /// #     type Channel = Channel;

diff --git a/src/nb/mod.rs b/src/nb/mod.rs
@@ -0,0 +1,23 @@
+//! Non-blocking API
+//!
+//! These traits make use of the [`nb`] crate
+//! (*please go read that crate documentation before continuing*) to abstract over
+//! the execution model and to also provide an optional blocking operation mode.
+//!
+//! The `nb::Result` enum is used to add an [`Error::WouldBlock`] variant to the errors
+//! of the traits. Using this it is possible to execute actions in a non-blocking
+//! way.
+//!
+//! `block!`, `Result` and `Error` from the [`nb`] crate are re-exported here to avoid
+//! crate version mismatches. These should be used instead of importing the `nb` crate
+//! directly again in dependent crates.
+//!
+//! [`nb`]: https://crates.io/crates/nb
+
+pub use nb::{block, Error, Result};
+pub mod adc;
+pub mod capture;
+pub mod rng;
+pub mod serial;
+pub mod spi;
+pub mod timer;
diff --git a/src/rng.rs → src/nb/rng.rs b/src/rng.rs → src/nb/rng.rs
@@ -1,7 +1,5 @@
 //! Random Number Generator Interface
 
-use nb;
-
 /// Nonblocking stream of random bytes.
 pub trait Read {
     /// An enumeration of RNG errors.

diff --git a/src/serial.rs → src/nb/serial.rs b/src/serial.rs → src/nb/serial.rs
diff --git a/src/spi.rs → src/nb/spi.rs b/src/spi.rs → src/nb/spi.rs
diff --git a/src/timer.rs → src/nb/timer.rs b/src/timer.rs → src/nb/timer.rs
@@ -47,7 +47,7 @@
 /// #     pub fn on(&mut self) {}
 /// # }
 /// # struct Timer6;
-/// # impl hal::timer::CountDown for Timer6 {
+/// # impl hal::nb::timer::CountDown for Timer6 {
 /// #     type Error = Infallible;
 /// #     type Time = Seconds;
 /// #     fn start<T>(&mut self, _: T) -> Result<(), Self::Error> where T: Into<Seconds> { Ok(()) }

diff --git a/src/prelude.rs b/src/prelude.rs
@@ -3,38 +3,38 @@
 //! The traits have been renamed to avoid collisions with other items when
 //! performing a glob import.
 
-pub use crate::adc::Channel as _embedded_hal_adc_Channel;
-pub use crate::adc::OneShot as _embedded_hal_adc_OneShot;
 pub use crate::blocking::delay::DelayMs as _embedded_hal_blocking_delay_DelayMs;
 pub use crate::blocking::delay::DelayUs as _embedded_hal_blocking_delay_DelayUs;
+pub use crate::blocking::digital::InputPin as _embedded_hal_blocking_digital_InputPin;
+pub use crate::blocking::digital::OutputPin as _embedded_hal_blocking_digital_OutputPin;
+pub use crate::blocking::digital::StatefulOutputPin as _embedded_hal_blocking_digital_StatefulOutputPin;
+pub use crate::blocking::digital::ToggleableOutputPin as _embedded_hal_blocking_digital_ToggleableOutputPin;
 pub use crate::blocking::i2c::{
     Read as _embedded_hal_blocking_i2c_Read,
     Transactional as _embedded_hal_blocking_i2c_Transactional,
     Write as _embedded_hal_blocking_i2c_Write, WriteIter as _embedded_hal_blocking_i2c_WriteIter,
     WriteIterRead as _embedded_hal_blocking_i2c_WriteIterRead,
     WriteRead as _embedded_hal_blocking_i2c_WriteRead,
 };
+pub use crate::blocking::pwm::Pwm as _embedded_hal_blocking_Pwm;
+pub use crate::blocking::pwm::PwmPin as _embedded_hal_blocking_PwmPin;
+pub use crate::blocking::qei::Qei as _embedded_hal_blocking_Qei;
 pub use crate::blocking::rng::Read as _embedded_hal_blocking_rng_Read;
 pub use crate::blocking::serial::Write as _embedded_hal_blocking_serial_Write;
 pub use crate::blocking::spi::{
     Transfer as _embedded_hal_blocking_spi_Transfer, Write as _embedded_hal_blocking_spi_Write,
     WriteIter as _embedded_hal_blocking_spi_WriteIter,
 };
-pub use crate::capture::Capture as _embedded_hal_Capture;
-pub use crate::digital::InputPin as _embedded_hal_digital_InputPin;
-pub use crate::digital::OutputPin as _embedded_hal_digital_OutputPin;
-pub use crate::digital::StatefulOutputPin as _embedded_hal_digital_StatefulOutputPin;
-pub use crate::digital::ToggleableOutputPin as _embedded_hal_digital_ToggleableOutputPin;
-pub use crate::pwm::Pwm as _embedded_hal_Pwm;
-pub use crate::pwm::PwmPin as _embedded_hal_PwmPin;
-pub use crate::qei::Qei as _embedded_hal_Qei;
-pub use crate::rng::Read as _embedded_hal_rng_Read;
-pub use crate::serial::Read as _embedded_hal_serial_Read;
-pub use crate::serial::Write as _embedded_hal_serial_Write;
-pub use crate::spi::FullDuplex as _embedded_hal_spi_FullDuplex;
-pub use crate::timer::Cancel as _embedded_hal_timer_Cancel;
-pub use crate::timer::CountDown as _embedded_hal_timer_CountDown;
-pub use crate::timer::Periodic as _embedded_hal_timer_Periodic;
-pub use crate::watchdog::Disable as _embedded_hal_watchdog_Disable;
-pub use crate::watchdog::Enable as _embedded_hal_watchdog_Enable;
-pub use crate::watchdog::Watchdog as _embedded_hal_watchdog_Watchdog;
+pub use crate::blocking::watchdog::Disable as _embedded_hal_blocking_watchdog_Disable;
+pub use crate::blocking::watchdog::Enable as _embedded_hal_blocking_watchdog_Enable;
+pub use crate::blocking::watchdog::Watchdog as _embedded_hal_blocking_watchdog_Watchdog;
+pub use crate::nb::adc::Channel as _embedded_hal_nb_adc_Channel;
+pub use crate::nb::adc::OneShot as _embedded_hal_nb_adc_OneShot;
+pub use crate::nb::capture::Capture as _embedded_hal_nb_Capture;
+pub use crate::nb::rng::Read as _embedded_hal_nb_rng_Read;
+pub use crate::nb::serial::Read as _embedded_hal_nb_serial_Read;
+pub use crate::nb::serial::Write as _embedded_hal_nb_serial_Write;
+pub use crate::nb::spi::FullDuplex as _embedded_hal_nb_spi_FullDuplex;
+pub use crate::nb::timer::Cancel as _embedded_hal_nb_timer_Cancel;
+pub use crate::nb::timer::CountDown as _embedded_hal_nb_timer_CountDown;
+pub use crate::nb::timer::Periodic as _embedded_hal_nb_timer_Periodic;