1# Chapter 9 - Understanding Pointers
2 
3Many higher level languages hide memory management, typically **passing by value** (copy data) or **passing by reference** (reference to shared data) without worrying about allocation, heap, stack, ownership and lifetimes, it is all delegated to the garbage collector or VM. Here is a comparison on this topic between a few languages:
4 
5### 📌 Language Comparison 
6 
7| Language | Value Types | Reference/Pointer Types | Async Model & Types | Manual Memory |
8|------------ |------------------------------------- |----------------------------------------------------------- |---------------------------------------------------------------------------- |------------------------------ |
9| Python | None | Everything is a reference | async def, await, Task, coroutines and asyncio.Future | ❌ Not Allowed |
10| Javascript | Primitives | Objects | `async/await`, `Promise`, `setTimeout`. single threaded event loop | ❌ Not Allowed |
11| Java | Primitives | Objects | `Future<T>`, threads, Loom (green threads) | ❌ Almost none & not recommended |
12| Go | Values are copied unless using `&T` | Pointers (`*T`, `&T`), escape analysis | goroutines, `channels`, `sync.Mutex`, `context.Context` | ⚠️ Limited |
13| C | Primitives and structs supported | Raw pointers `T*` and `*void` | Threads, event loops (`libuv`, `libevent`) | ✅ Fully |
14| C++ | Primitives and references | Raw `T*` and smart pointers `shared_ptr` and `unique_ptr` | threads, `std::future`, `std::async`, (since c++ 20 `co_await/coroutines`) | ✅ Mostly |
15| Rust | Primitives, Arrays, `impl Copy` | `&T`, `&mut T`, `Box<T>`, `Arc<T>` | `async/await`, `tokio`, `Future`, `JoinHandle`, `Send + Sync` | ✅🔒 Safe and Explicit |
16 
17## 9.1 Thread Safety
18 
19Rust tracks pointers using `Send` and `Sync` traits:
20- `Send` means data can move across threads.
21- `Sync` means data can be referenced from multiple threads.
22 
23> A pointer is thread-safe only if the data behind it is.
24 
25| Pointer Type | Short Description | Send + Sync? | Main Use |
26|---------------- |--------------------------------------------------------------------------- |-------------------------------------- |------------ |
27| `&T` | Shared reference | Yes | Shared access |
28| `&mut T` | Exclusive mutable reference | No, not Send | Exclusive mutation |
29| `Box<T>` | Heap-allocated owning pointer | Yes, if T: Send + Sync | Heap allocation |
30| `Rc<T>` | Single-threaded ref counted pointer | No, neither | Multiple owners (single-thread) |
31| `Arc<T>` | Atomic ref counter pointer | Yes | Multiple owners (multi-thread) |
32| `Cell<T>` | Interior mutability for copy types | No, not Sync | Shared mutable, non-threaded |
33| `RefCell<T>` | Interior mutability (dynamic borrow checker) | No, not Sync | Shared mutable, non-threaded |
34| `Mutex<T>` | Thread-safe interior mutability with exclusive access | Yes | Shared mutable, threaded |
35| `RwLock<T>` | Thread-safe shared readonly access OR exclusive mutable access | Yes | Shared mutable, threaded |
36| `OnceCell<T>` | Single-thread one-time initialization container (interior mutability ONCE) | No, not Sync | Simple lazy value initialization |
37| `LazyCell<T>` | A lazy version of `OnceCell<T>` that calls function closure to initialize | No, not Sync | Complex lazy value initialization |
38| `OnceLock<T>` | Thread-safe version of `OnceCell<T>` | Yes | Multi-thread single init |
39| `LazyLock<T>` | Thread-safe version of `LazyCell<T>` | Yes | Multi-thread complex init |
40| `*const T/*mut T` | Raw Pointers | No, user must ensure safety manually | Raw memory / FFI |
41 
42## 9.2 When to use pointers:
43 
44### `&T` - Shared Borrow:
45 
46Probably the most common type in a Rust code base, it is **Safe, with no mutation** and allows **multiple readers**.
47 
48```rust
49let data: String = String::from_str("this a string").unwrap();
50 
51print_len(&data);
52print_capacity(&data);
53print_bytes(&data);
54 
55fn print_len(s: &str) {
56    println!("{}", s.len())
57}
58 
59fn print_capacity(s: &String) {
60    println!("{}", s.capacity())
61}
62 
63fn print_bytes(s: &String) {
64    println!("{:?}", s.as_bytes())
65}
66```
67### `&mut T` - Exclusive Borrow:
68 
69Probably the most common *mutable* type in a Rust code base, it is **Safe, but only allows one mutable borrow at a time**.
70 
71```rust
72let mut data: String = String::from_str("this a string").unwrap();
73mark_update(&mut data);
74 
75fn mark_update(s: &mut String) {
76    s.push_str("_update");
77}
78```
79 
80### [`Box<T>`](https://doc.rust-lang.org/std/boxed/struct.Box.html) - Heap Allocated
81 
82Single-owner heap-allocated data, great for recursive types and large structs.
83 
84```rust
85pub enum MySubBoxedEnum<T> {
86    Single(T),
87    Double(Box<MySubBoxedEnum<T>>, Box<MySubBoxedEnum<T>>),
88    Multi(Vec<T>), // Note that Vec is already a boxed value
89}
90```
91 
92### [`Rc<T>`](https://doc.rust-lang.org/std/rc/struct.Rc.html) - Reference Counter (single-thread)
93 
94You need multiple references to data in a single thread. Most common example is linked-list implementation.
95 
96### [`Arc<T>`](https://doc.rust-lang.org/std/sync/struct.Arc.html) - Atomic Reference Counter (multi-thread)
97 
98You need multiple references to data in multiple threads. Most common use cases is sharing readonly Vec across thread with `Arc<[T]>` and wrapping a `Mutex` so it can be easily shared across threads, `Arc<Mutex<T>>`.
99 
100### [`RefCell<T>`](https://doc.rust-lang.org/std/cell/struct.RefCell.html) - Runtime checked interior mutability
101 
102Used when you need shared access and the ability to mutate date, borrow rules are enforced at runtime. **It may panic!**.
103 
104```rust
105use std::cell::RefCell;
106let x = RefCell::new(42);
107*x.borrow_mut() += 1;
108 
109assert_eq!(&*x.borrow(), 42, "Not meaning of life");
110```
111 
112Panic example:
113```rust
114use std::cell::RefCell;
115let x = RefCell::new(42);
116 
117let borrow = x.borrow();
118 
119let mutable = x.borrow_mut();
120```
121 
122### [`Cell<T>`](https://doc.rust-lang.org/std/cell/struct.Cell.html) - Copy-only interior mutability
123 
124Somewhat the fast and safe version of `RefCell`, but it is limited to types that implement the `Copy` trait:
125 
126```rust
127use std::cell::Cell;
128 
129struct SomeStruct {
130    regular_field: u8,
131    special_field: Cell<u8>,
132}
133 
134let my_struct = SomeStruct {
135    regular_field: 0,
136    special_field: Cell::new(1),
137};
138 
139let new_value = 100;
140 
141// ERROR: `my_struct` is immutable
142// my_struct.regular_field = new_value;
143 
144// WORKS: although `my_struct` is immutable, `special_field` is a `Cell`,
145// which can always be mutated with copy values
146my_struct.special_field.set(new_value);
147assert_eq!(my_struct.special_field.get(), new_value);
148```
149 
150### [`Mutex<T>`](https://doc.rust-lang.org/std/sync/struct.Mutex.html) - Thread-safe mutability
151 
152An exclusive access pointer that allows a thread to read/write the data contained inside. It is usually wrapped in an `Arc` to allow shared access to the Mutex.
153 
154### [`RwLock<T>`](https://doc.rust-lang.org/std/sync/struct.RwLock.html) - Thread-safe mutability
155 
156Similar to a `Mutex`, but it allows multiple threads to read it OR a single thread to write. It is usually wrapped in an `Arc` to allow shared access to the RwLock.
157 
158 
159### [`*const T/*mut T`](https://doc.rust-lang.org/std/primitive.pointer.html) - Raw pointers
160 
161Inherently **unsafe** and necessary for FFI. Rust makes their usage explicit to avoid accidental misuse and unwilling manual memory management.
162 
163```rust
164let x = 5;
165let ptr = &x as *const i32;
166unsafe {
167    println!("PTR is {}", *ptr)
168}
169```
170 
171### [`OnceCell`](https://doc.rust-lang.org/std/cell/struct.OnceCell.html) - Single-thread single initialization container
172 
173Most useful when you need to share a configuration between multiple data structures.
174 
175```rust
176use std::{cell::OnceCell, rc::Rc};
177 
178#[derive(Debug, Default)]
179struct MyStruct {
180    distance: usize,
181    root: Option<Rc<OnceCell<MyStruct>>>, 
182}
183 
184fn main() {
185    let root = MyStruct::default();
186    let root_cell = Rc::new(OnceCell::new());
187    if let Err(previous) = root_cell.set(root) {
188        eprintln!("Previous Root {previous:?}");
189    }
190    let child_1 = MyStruct{
191        distance: 1,
192        root: Some(root_cell.clone())
193    };
194 
195    let child_2 = MyStruct{
196        distance: 2,
197        root: Some(root_cell.clone())
198    };
199 
200 
201    println!("Child 1: {child_1:?}");
202    println!("Child 2: {child_2:?}");
203}
204```
205 
206### [`LazyCell`](https://doc.rust-lang.org/std/cell/struct.LazyCell.html) - Lazy initialization of `OnceCell`
207 
208Useful when the initialized data can be delayed to when it is actually being called.
209 
210### [`OnceLock`](https://doc.rust-lang.org/std/sync/struct.OnceLock.html) - thread-safe `OnceCell`
211 
212Useful when you need a `static` value.
213 
214```rust
215use std::sync::OnceLock;
216 
217static CELL: OnceLock<u32> = OnceLock::new();
218 
219// `OnceLock` has not been written to yet.
220assert!(CELL.get().is_none());
221 
222// Spawn a thread and write to `OnceLock`.
223std::thread::spawn(|| {
224    let value = CELL.get_or_init(|| 12345);
225    assert_eq!(value, &12345);
226})
227.join()
228.unwrap();
229 
230// `OnceLock` now contains the value.
231assert_eq!(
232    CELL.get(),
233    Some(&12345),
234);
235```
236 
237### [`LazyLock`](https://doc.rust-lang.org/std/sync/struct.LazyLock.html) - thread-safe `LazyCell`
238 
239Similar to `OnceLock`, but the static value is a bit more complex to initialize.
240 
241```rust
242use std::sync::LazyLock;
243 
244static CONFIG: LazyLock<HashMap<&str, T>> = LazyLock::new(|| {
245    let data = read_config();
246    let mut config: HashMap<&str, T> = data.into();
247    config.insert("special_case", T::default());
248    config
249});
250 
251let _ = &*CONFIG;
252```
253 
254## References
255- [Mara Bos - Rust Atomics and Locks](https://marabos.nl/atomics/)
256- [Semicolon video on pointers](https://www.youtube.com/watch?v=Ag_6Q44PBNs)
257