1 | //! # Note on version 0.10.3 |
2 | //! |
3 | //! This version of `self_cell` is a re-export of the `self_cell` version `1` |
4 | //! meant for backwards-compatibly allowing `0.10` users to get current and |
5 | //! future soundness fixes. If you are adding `self_cell` as a dependency, |
6 | //! please use an up-to-date version directly. |
7 | //! |
8 | //! # Overview |
9 | //! |
10 | //! `self_cell` provides one macro-rules macro: [`self_cell`][`self_cell!`]. With this macro |
11 | //! you can create self-referential structs that are safe-to-use in stable Rust, |
12 | //! without leaking the struct internal lifetime. |
13 | //! |
14 | //! In a nutshell, the API looks *roughly* like this: |
15 | //! |
16 | //! ```ignore |
17 | //! // User code: |
18 | //! |
19 | //! self_cell!( |
20 | //! struct NewStructName { |
21 | //! owner: Owner, |
22 | //! |
23 | //! #[covariant] |
24 | //! dependent: Dependent, |
25 | //! } |
26 | //! |
27 | //! impl {Debug} |
28 | //! ); |
29 | //! |
30 | //! // Generated by macro: |
31 | //! |
32 | //! struct NewStructName(...); |
33 | //! |
34 | //! impl NewStructName { |
35 | //! fn new( |
36 | //! owner: Owner, |
37 | //! dependent_builder: impl for<'a> FnOnce(&'a Owner) -> Dependent<'a> |
38 | //! ) -> NewStructName { ... } |
39 | //! fn borrow_owner<'a>(&'a self) -> &'a Owner { ... } |
40 | //! fn borrow_dependent<'a>(&'a self) -> &'a Dependent<'a> { ... } |
41 | //! } |
42 | //! |
43 | //! impl Debug for NewStructName { ... } |
44 | //! ``` |
45 | //! |
46 | //! Self-referential structs are currently not supported with safe vanilla Rust. |
47 | //! The only reasonable safe alternative is to have the user juggle 2 separate |
48 | //! data structures which is a mess. The library solution ouroboros is really |
49 | //! expensive to compile due to its use of procedural macros. |
50 | //! |
51 | //! This alternative is `no_std`, uses no proc-macros, some self contained |
52 | //! unsafe and works on stable Rust, and is miri tested. With a total of less |
53 | //! than 300 lines of implementation code, which consists mostly of type and |
54 | //! trait implementations, this crate aims to be a good minimal solution to the |
55 | //! problem of self-referential structs. |
56 | //! |
57 | //! It has undergone [community code |
58 | //! review](https://users.rust-lang.org/t/experimental-safe-to-use-proc-macro-free-self-referential-structs-in-stable-rust/52775) |
59 | //! from experienced Rust users. |
60 | //! |
61 | //! ### Fast compile times |
62 | //! |
63 | //! ```txt |
64 | //! $ rm -rf target && cargo +nightly build -Z timings |
65 | //! |
66 | //! Compiling self_cell v0.7.0 |
67 | //! Completed self_cell v0.7.0 in 0.2s |
68 | //! ``` |
69 | //! |
70 | //! Because it does **not** use proc-macros, and has 0 dependencies |
71 | //! compile-times are fast. |
72 | //! |
73 | //! Measurements done on a slow laptop. |
74 | //! |
75 | //! ### A motivating use case |
76 | //! |
77 | //! ```rust |
78 | //! use self_cell::self_cell; |
79 | //! |
80 | //! #[derive(Debug, Eq, PartialEq)] |
81 | //! struct Ast<'a>(pub Vec<&'a str>); |
82 | //! |
83 | //! self_cell!( |
84 | //! struct AstCell { |
85 | //! owner: String, |
86 | //! |
87 | //! #[covariant] |
88 | //! dependent: Ast, |
89 | //! } |
90 | //! |
91 | //! impl {Debug, Eq, PartialEq} |
92 | //! ); |
93 | //! |
94 | //! fn build_ast_cell(code: &str) -> AstCell { |
95 | //! // Create owning String on stack. |
96 | //! let pre_processed_code = code.trim().to_string(); |
97 | //! |
98 | //! // Move String into AstCell, then build Ast inplace. |
99 | //! AstCell::new( |
100 | //! pre_processed_code, |
101 | //! |code| Ast(code.split(' ' ).filter(|word| word.len() > 1).collect()) |
102 | //! ) |
103 | //! } |
104 | //! |
105 | //! fn main() { |
106 | //! let ast_cell = build_ast_cell("fox = cat + dog" ); |
107 | //! |
108 | //! println!("ast_cell -> {:?}" , &ast_cell); |
109 | //! println!("ast_cell.borrow_owner() -> {:?}" , ast_cell.borrow_owner()); |
110 | //! println!("ast_cell.borrow_dependent().0[1] -> {:?}" , ast_cell.borrow_dependent().0[1]); |
111 | //! } |
112 | //! ``` |
113 | //! |
114 | //! ```txt |
115 | //! $ cargo run |
116 | //! |
117 | //! ast_cell -> AstCell { owner: "fox = cat + dog", dependent: Ast(["fox", "cat", "dog"]) } |
118 | //! ast_cell.borrow_owner() -> "fox = cat + dog" |
119 | //! ast_cell.borrow_dependent().0[1] -> "cat" |
120 | //! ``` |
121 | //! |
122 | //! There is no way in safe Rust to have an API like `build_ast_cell`, as soon |
123 | //! as `Ast` depends on stack variables like `pre_processed_code` you can't |
124 | //! return the value out of the function anymore. You could move the |
125 | //! pre-processing into the caller but that gets ugly quickly because you can't |
126 | //! encapsulate things anymore. Note this is a somewhat niche use case, |
127 | //! self-referential structs should only be used when there is no good |
128 | //! alternative. |
129 | //! |
130 | //! Under the hood, it heap allocates a struct which it initializes first by |
131 | //! moving the owner value to it and then using the reference to this now |
132 | //! Pin/Immovable owner to construct the dependent inplace next to it. This |
133 | //! makes it safe to move the generated SelfCell but you have to pay for the |
134 | //! heap allocation. |
135 | //! |
136 | //! See the documentation for [`self_cell`][`self_cell!`] to dive further into the details. |
137 | //! |
138 | //! Or take a look at the advanced examples: |
139 | //! - [Example how to handle dependent construction that can |
140 | //! fail](https://github.com/Voultapher/self_cell/tree/main/examples/fallible_dependent_construction) |
141 | //! |
142 | //! - [How to build a lazy AST with |
143 | //! self_cell](https://github.com/Voultapher/self_cell/tree/main/examples/lazy_ast) |
144 | //! |
145 | //! - [How to use an owner type with |
146 | //! lifetime](https://github.com/Voultapher/self_cell/tree/main/examples/owner_with_lifetime) |
147 | //! |
148 | //! ### Min required rustc version |
149 | //! |
150 | //! By default the minimum required rustc version is 1.51. |
151 | //! |
152 | //! There is an optional feature you can enable called "old_rust" that enables |
153 | //! support down to rustc version 1.36. However this requires polyfilling std |
154 | //! library functionality for older rustc with technically UB versions. Testing |
155 | //! does not show older rustc versions (ab)using this. Use at your own risk. |
156 | //! |
157 | //! The minimum versions are a best effor and may change with any new major |
158 | //! release. |
159 | |
160 | #![no_std ] |
161 | |
162 | pub use new_self_cell::self_cell; |
163 | |