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
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
//! Behavior and guarantees provided by types to be in and out of memory.
use MaybeUninit;
/// A marker trait that describes an "immortal" type.
///
/// By "immortal", this denotes a type that is fixed in size and has no lifetime dependencies.
/// Blanket implementation for all "immortal" types.
/// A trait that models an unassociated (i.e., no attached lifetime, immortal), trivially-copiable type that can be read from memory.
///
/// # Hardware Coherence Model
///
/// When dealing with concurrent, un-synchronized memory reads, understanding the physical hardware access model is critical:
///
/// * **Machine-Word Coherence:** The hardware guarantee that a CPU can fetch data up to its native word size (e.g., 64-bits on x86_64) in a single, indivisible memory bus transaction.
/// * **Snapshot Coherence:** A read resulting from a single, indivisible transaction. The resulting value represents the exact state of the memory at an isolated point in time.
/// * **Mixed Coherence (Tearing):** A read assembled from multiple hardware transactions. If another thread mutates the memory between these fetches, the resulting value is a temporal mix of old and new bytes.
///
/// Mixed coherence inevitably occurs under two conditions:
/// 1. The data type exceeds the hardware machine word (e.g., attempting a concurrent read on a 256-byte `struct`).
/// 2. The memory access is **unaligned**. For example, reading an 8-byte `u64` that physically straddles two distinct CPU cachelines forces the hardware to split the read into two distinct fetches, immediately destroying snapshot coherence.
///
/// # Safety
///
/// To be able to implement this trait safely, all the following requirements must have been satisfied:
///
/// * The type is valid and presents no broken safety-related invariants in all possible bit-permutations, as well as be able to survive a round-trip through both bitstream and whole-type states.
/// * The type must be appropriate for snapshot and mixed-coherence reads. Particularly, for a single-component type, it must be safe to read and write from a
/// concurrently mutated memory region where tearing is inherently permitted, without resulting in type-level undefined behavior. For a multi-component type, it may present inter-component tearing, but the individual components still correspond to a valid observed value.
/// * The type is safe to transmute back-and-forth to a byte-level representation.
///
/// As a general rule, do not implement this for types or any primitive that possesses an illegal bit-pattern (e.g., `bool`, or an enum with a non-explicit **repr** with non-exhaustive discriminants).
///
/// # Data Validity
///
/// As a global concern, validate that:
///
/// - The alignment for the type you're reading is correct.
/// - The type itself or individual primitive components do not cross cacheline boundaries.
///
/// If these concerns are not satified, the data remains safe to read, but may prove of little use due to low validity.
pub unsafe
// SAFETY: If `T` implements `Unassociated`, `MaybeUninit` does too.
unsafe
// SAFETY: Unsigned 8-bit integers possess no safety-related invariants and are valid for all possible bit-permutations.
unsafe
// SAFETY: Signed 8-bit integers possess no safety-related invariants and are valid for all possible bit-permutations.
unsafe
// SAFETY: Unsigned 16-bit integers possess no safety-related invariants and are valid for all possible bit-permutations.
unsafe
// SAFETY: Signed 16-bit integers possess no safety-related invariants and are valid for all possible bit-permutations.
unsafe
// SAFETY: Unsigned 32-bit integers possess no safety-related invariants and are valid for all possible bit-permutations.
unsafe
// SAFETY: Signed 32-bit integers possess no safety-related invariants and are valid for all possible bit-permutations.
unsafe
// SAFETY: Unsigned 64-bit integers possess no safety-related invariants and are valid for all possible bit-permutations.
unsafe
// SAFETY: Signed 64-bit integers possess no safety-related invariants and are valid for all possible bit-permutations.
unsafe
// SAFETY: Pointer-sized unsigned integers possess no safety-related invariants and are valid for all possible bit-permutations.
unsafe
// SAFETY: Pointer-sized signed integers possess no safety-related invariants and are valid for all possible bit-permutations.
unsafe
// SAFETY: 32-bit floats possess no safety-related invariants. NaN bit patterns are mathematically valid states.
unsafe
// SAFETY: 64-bit floats possess no safety-related invariants. NaN bit patterns are mathematically valid states.
unsafe
// SAFETY: The element type `U` implements `Unassociated`, therefore, a const-generic array does too.
unsafe
// SAFETY: A thin raw pointer has no illegal bit patterns, as every bit pattern is a valid
// pointer value, it is byte-transmutable, and a torn read still yields a valid (if mangled and
// meaningless) address that is never dereferenced. The `P: Immortal` bound supplies
// `Sized` (the pointer is thin, a single machine word) and `'static` (satisfying the
// `Immortal` supertrait of `Unassociated`).
// NOTE(warning): This is to be used as an escape hatch to model pointers in a foreign address space.
unsafe
// SAFETY: A thin raw pointer has no illegal bit patterns, as every bit pattern is a valid
// pointer value, it is byte-transmutable, and a torn read still yields a valid (if mangled and
// meaningless) address that is never dereferenced. The `P: Immortal` bound supplies
// `Sized` (the pointer is thin, a single machine word) and `'static` (satisfying the
// `Immortal` supertrait of `Unassociated`).
// NOTE(warning): This is to be used as an escape hatch to model pointers in a foreign address space.
unsafe