no_alloc/lib.rs
1//! Embedded friendly pointer types for `no_std` applications without heap
2//! allocators.
3//!
4//! # Usage
5//!
6//! `no_alloc` can be used to create boxes for dynamically sized types without
7//! heap allocation:
8//!
9//! ```ignore
10//! #![no_main]
11//! #![no_std]
12//!
13//! use core::any::Any;
14//!
15//! use cortex_m_rt::entry;
16//! use no_alloc::{boxed_s, BoxS};
17//!
18//! #[entry]
19//! fn main() -> ! {
20//! let boxed: BoxS<dyn Any, [usize; 1]> = boxed_s!(0_isize);
21//! assert_eq!(boxed.downcast_ref::<isize>(), Some(&0));
22//! loop {
23//! // Application logic
24//! }
25//! }
26//! ```
27//!
28//! Compile-time assertions are made to ensure that pointers will always be
29//! backed by enough memory and have the correct alignment. The following will
30//! fail to compile:
31//!
32//! ```compile_fail
33//! use core::any::Any;
34//! use no_alloc::BoxS;
35//!
36//! let _impossible: BoxS<dyn Any, [usize; 0]> = boxed_s!(0_isize);
37//! ```
38//!
39//! For more information, consult the documentation for [`BoxS::new`].
40//!
41//! [`BoxS::new`]: struct.BoxS.html#method.new
42//!
43//! # Dependencies
44//!
45//! `no_alloc` has no runtime dependencies.
46//!
47//! [`heapless`] can be optionally brought in to add support for boxes backed by
48//! global memory pools by activating the `pool` feature.
49//!
50//! [`heapless`]: https://docs.rs/heapless
51//!
52//! # Features
53//!
54//! * `coerce_unsized`
55//!
56//! **This feature requires a nightly toolchain**
57//!
58//! Implements [`CoerceUnsized`] for [`BoxS`], circumventing the requirement
59//! for the [`boxed_s`] macro:
60//!
61//! ```
62//! # #[cfg(feature = "coerce_unsized")]
63//! # {
64//! use core::any::Any;
65//! use no_alloc::BoxS;
66//!
67//! let boxed: BoxS<dyn Any, [usize; 1]> = BoxS::new(0_isize);
68//! # }
69//! ```
70//!
71//! [`CoerceUnsized`]: https://doc.rust-lang.org/stable/core/ops/trait.CoerceUnsized.html
72//! [`BoxS`]: struct.BoxS.html
73//! [`boxed_s`]: macro.boxed.html
74//!
75//! * `const_generics`
76//!
77//! **This feature requires a nightly toolchain**
78//!
79//! Implements [`Memory`] for arrays of any aribtrary length, rather than
80//! a few select lengths.
81//!
82//! [`Memory`]: trait.Memory.html
83//!
84//! * `pool`
85//!
86//! Enables smart pointers allocated from a global memory pool. This will
87//! drag in [`heapless`] as a dependency.
88//!
89//! [`heapless`]: https://docs.rs/heapless
90//!
91//! # Safety
92//!
93//! Safety is paramount to `no_alloc`.
94//!
95//! It works on top of a lot of unsafe code, but the exposed APIs are 100% safe.
96//!
97//! The crate is extensively tested, and these tests are run through [**Miri**]
98//! as part of the CI for the crate. Commits that fail the [**Miri**] stage
99//! cannot be merged to master and are forbidden from being released to
100//! [crates.io].
101//!
102//! [**Miri**]: https://github.com/rust-lang/miri
103//! [crates.io]: https://crates.io
104
105#![no_std]
106#![cfg_attr(rustdoc, feature(doc_cfg))]
107#![cfg_attr(feature = "coerce_unsized", feature(coerce_unsized, unsize))]
108#![cfg_attr(feature = "const_generics", feature(const_generics))]
109
110mod assert;
111mod boxed_s;
112mod mem;
113mod ptr;
114mod raw;
115
116pub use boxed_s::BoxS;
117pub use mem::Memory;
118
119#[cfg(feature = "pool")]
120#[cfg_attr(rustdoc, doc(cfg(feature = "pool")))]
121mod boxed;
122
123#[cfg(feature = "pool")]
124#[cfg_attr(rustdoc, doc(cfg(feature = "pool")))]
125pub use boxed::Box;