os_trait/
lib.rs

1//! Traits used to adapter different embedded RTOS.
2//! It defines a trait [`OsInterface`].
3//!
4//! We use the [`mutex-traits`](https://crates.io/crates/mutex-traits) crate to provide mutex functionality.
5//! You can implement your own mutex by implementing the `RawMutex` trait from the `mutex-traits` crate.
6//!
7//! # Example
8//!
9//! ```
10//! use os_trait::{prelude::*, FakeOs, StdOs, Duration, Timeout, Instant};
11//!
12//! fn use_os<OS: OsInterface>() {
13//!     let mutex = OS::mutex(2);
14//!
15//!     let mut guard = mutex.try_lock().unwrap();
16//!     assert_eq!(*guard, 2);
17//!
18//!     OS::yield_thread();
19//!     OS::delay().delay_ms(1);
20//!
21//!     let mut t = Timeout::<OS>::millis(1);
22//!     if t.timeout() {
23//!         // handle timeout
24//!     }
25//!
26//!     let mut now = Instant::<OS>::now();
27//!     now.elapsed();
28//!     if now.timeout(&Duration::<OS>::millis(1)) {}
29//!
30//!     let (notifier, waiter) = OS::notify();
31//!     assert!(notifier.notify());
32//!     assert!(waiter.wait(&Duration::<OS>::millis(1)));
33//! }
34//!
35//! fn select_os() {
36//!     use_os::<FakeOs>();
37//!     use_os::<StdOs>();
38//! }
39//! ```
40//!
41//! Use alias for convenience:
42//! ```
43//! use os_trait::{prelude::*, StdOs as OS, os_type_alias};
44//!
45//! os_type_alias!(OS);
46//!
47//! fn use_os_type() {
48//!     let mutex = Mutex::new(2);
49//!     OS::yield_thread();
50//!     OS::delay().delay_ms(1);
51//!
52//!     let t = Timeout::millis(1);
53//!     let dur = Duration::millis(1);
54//!     let mut now = Instant::now();
55//!     if now.timeout(&dur) {}
56//!
57//!     let (notifier, waiter) = OS::notify();
58//!     assert!(notifier.notify());
59//!     assert!(waiter.wait(&Duration::millis(1)));
60//! }
61//! ```
62
63#![cfg_attr(not(feature = "std"), no_std)]
64
65pub mod mutex;
66pub mod notifier;
67pub mod notifier_impls;
68pub mod os_impls;
69pub mod prelude;
70
71pub use fugit;
72pub use mutex::{BlockingMutex, FakeRawMutex};
73pub use mutex_traits;
74pub use mutex_traits::{ConstInit, RawMutex};
75pub use notifier::*;
76pub use notifier_impls::*;
77pub use os_impls::{FakeOs, StdOs};
78pub use timeout_trait::{self, *};
79
80#[cfg(feature = "alloc")]
81extern crate alloc;
82
83/// The interface for different operating systems.
84pub trait OsInterface: Send + Sync + Sized + 'static {
85    type RawMutex: ConstInit + RawMutex;
86    type Notifier: NotifierInterface;
87    type NotifyWaiter: NotifyWaiterInterface<Self>;
88    type Instant: TickInstant;
89    type Delay: DelayNs;
90
91    /// It's used to avoid writing `foo::<OS, _, _, _>(...)`
92    const O: Self;
93
94    fn yield_thread();
95
96    #[inline(always)]
97    fn yield_task() {
98        Self::yield_thread()
99    }
100
101    fn delay() -> Self::Delay;
102    fn notify() -> (Self::Notifier, Self::NotifyWaiter);
103
104    #[inline]
105    fn mutex<T>(d: T) -> Mutex<Self, T> {
106        Mutex::<Self, T>::new(d)
107    }
108}
109
110pub type Mutex<OS, T> = BlockingMutex<<OS as OsInterface>::RawMutex, T>;
111pub type Notifier<OS> = <OS as OsInterface>::Notifier;
112pub type NotifyWaiter<OS> = <OS as OsInterface>::NotifyWaiter;
113pub type Instant<OS> = <OS as OsInterface>::Instant;
114pub type Duration<OS> = TickDuration<Instant<OS>>;
115pub type Timeout<OS> = TickTimeout<Instant<OS>>;
116pub type Delay<OS> = <OS as OsInterface>::Delay;
117
118/// Use this macro to alias the OS-specific types for greater convenience,
119/// or manually alias only the ones you need.
120#[macro_export]
121macro_rules! os_type_alias {
122    ($YOUR_OS:ty) => {
123        pub type Mutex<T> = $crate::Mutex<$YOUR_OS, T>;
124        pub type Notifier = $crate::Notifier<$YOUR_OS>;
125        pub type NotifyWaiter = $crate::NotifyWaiter<$YOUR_OS>;
126        pub type Instant = $crate::Instant<$YOUR_OS>;
127        pub type Duration = $crate::Duration<$YOUR_OS>;
128        pub type Timeout = $crate::Timeout<$YOUR_OS>;
129        pub type Delay = $crate::Delay<$YOUR_OS>;
130    };
131}
os_trait/lib.rs

os_trait/
lib.rs
