1Managed
2=======
3
4_managed_ is a library that provides a way to logically own objects, whether or not
5heap allocation is available. It works with rustc 1.26 or later.
6
7Motivation
8----------
9
10The _managed_ library exists at the intersection of three concepts: _heap-less environments_,
11_collections_ and _generic code_. Consider this struct representing a network interface:
12
13```rust
14pub struct Interface<'a, 'b: 'a,
15    DeviceT:        Device,
16    ProtocolAddrsT: BorrowMut<[IpAddress]>,
17    SocketsT:       BorrowMut<[Socket<'a, 'b>]>
18> {
19    device:         DeviceT,
20    hardware_addr:  EthernetAddress,
21    protocol_addrs: ProtocolAddrsT,
22    sockets:        SocketsT,
23    phantom:        PhantomData<Socket<'a, 'b>>
24}
25```
26
27There are three things the struct `Interface` is parameterized over:
28  * an object implementing the trait `DeviceT`, which it owns;
29  * a slice of `IPAddress`es, which it either owns or borrows mutably;
30  * a slice of `Socket`s, which it either owns or borrows mutably, and which further either
31    own or borrow some memory.
32
33The motivation for using `BorrowMut` is that in environments with heap, the struct ought to
34own a `Vec`; on the other hand, without heap there is neither `Vec` nor `Box`, and it is only
35possible to use a `&mut`. Both of these implement BorrowMut.
36
37Note that owning a `BorrowMut` in this way does not hide the concrete type inside `BorrowMut`;
38if the slice is backed by a `Vec` then the `Vec` may still be resized by external code,
39although not the implementation of `Interface`.
40
41In isolation, this struct is easy to use. However, when combined with another codebase, perhaps
42embedded in a scheduler, problems arise. The type parameters have to go somewhere! There
43are two choices:
44  * either the type parameters, whole lot of them, infect the scheduler and push ownership
45    even higher in the call stack (self-mutably-borrowing structs are not usable in safe Rust,
46    so the scheduler could not easily own the slices);
47  * or the interface is owned as a boxed trait object, excluding heap-less systems.
48
49Clearly, both options are unsatisfying. Enter _managed_!
50
51Installation
52------------
53
54To use the _managed_ library in your project, add the following to `Cargo.toml`:
55
56```toml
57[dependencies]
58managed = "0.6"
59```
60
61The default configuration assumes a hosted environment, for ease of evaluation.
62You probably want to disable default features and configure them one by one:
63
64```toml
65[dependencies]
66managed = { version = "...", default-features = false, features = ["..."] }
67```
68
69### Feature `std`
70
71The `std` feature enables use of `Box`, `Vec`, and `BTreeMap` through a dependency
72on the `std` crate.
73
74### Feature `alloc`
75
76The `alloc` feature enables use of `Box`, `Vec`, and `BTreeMap` through a dependency
77on the `alloc` crate. It requires the use of nightly rustc.
78
79### Feature `map`
80
81The `map` feature, disabled by default, enables the `ManagedMap` enum.
82Its interface is not stable yet and is subject to change.
83It also requires the use of rustc 1.28 or later.
84
85Usage
86-----
87
88_managed_ is an interoperability crate: it does not include complex functionality but rather
89defines an interface that may be used by many downstream crates. It includes three enums:
90
91```rust
92pub enum Managed<'a, T: 'a + ?Sized> {
93    Borrowed(&'a mut T),
94    #[cfg(/* Box available */)]
95    Owned(Box<T>),
96}
97
98pub enum ManagedSlice<'a, T: 'a> {
99    Borrow(&'a mut [T]),
100    #[cfg(/* Vec available */)]
101    Owned(Vec<T>)
102}
103
104// The implementation of ManagedMap is not yet stable, beware!
105pub enum ManagedMap<'a, K: Hash + 'a, V: 'a> {
106    Borrowed(&'a mut [Option<(K, V)>]),
107    #[cfg(/* BTreeMap available */)]
108    Owned(BTreeMap<K, V>)
109}
110```
111
112The `Managed` and `ManagedSlice` enums have the `From` implementations from the corresponding
113types, and `Deref`/`DerefMut` implementations to the type `T`, as well as other helper methods,
114and `ManagedMap` is implemented using either a B-tree map or a sorted slice of key-value pairs.
115
116See the [full documentation][doc] for details.
117
118[doc]: https://docs.rs/managed/
119
120License
121-------
122
123_managed_ is distributed under the terms of 0-clause BSD license.
124
125See [LICENSE-0BSD](LICENSE-0BSD.txt) for details.
126