1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
//! A behavior trait defining how to read and write structural states of a block's metadata.
//!
//! This trait provides a unified API for the buddy allocator to query and modify state fields
//! (such as linked list pointers, current buddy orders, and ceil reduction limits)
//! of individual memory blocks.
//!
//! # Crucial Architectural Detail: Handle Passing vs. Direct References
//! A subtle but incredibly powerful aspect of this trait is that its methods **do not** take
//! a direct reference to the raw metadata struct (e.g., `&RawMetadata`). Instead, they accept
//! a reference to the **Metadata Handle** (`&Self::MetaData`).
//!
//! ### Why this is a game-changer for Rust's Borrow Checker:
//! 1. **Zero-Cost Abstraction over Indirection:** If your `MetaData` handle is defined as a mutable
//! static reference (like `&'static mut TestMetaData`), the method signature `&Self::MetaData`
//! evaluates to a double reference: `&&'static mut TestMetaData`.
//! 2. **Avoiding Lifetime Aliasing Violations:** The buddy allocator frequently needs to read
//! from and write to multiple block metadatas (e.g., during buddy lookup and unlinking) inside
//! the same scope. If we passed raw references, Rust's borrow checker would flag this as
//! multiple simultaneous mutable borrows.
//! 3. **Indirection Safety:** Passing a reference to the handle (`&Self::MetaData`) bypasses these
//! borrow-checking restrictions, allowing the allocator to perform fast, inline pointer
//! manipulations without wrapping metadata in expensive runtime-checked wrappers like `RefCell`.