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
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
use ptr;
/// 一个持有类型化可变裸指针(`*mut T`)的包装结构,用于快捷地跨线程传递原始指针。
///
/// # 设计意图
/// 该类型允许将任意类型的可变裸指针包装起来,并在类型层面保留指针所指向的数据类型 `T`。
/// 它本身不管理内存、不保证有效性、不提供生命周期关联——所有安全性均由调用者负责。
/// 适合在需要绕过 Rust 所有权/借用检查,但又希望保持一定类型一致性的场景(如 FFI 或底层跨线程传递)。
///
/// # 安全性总览
/// **该类型的所有方法均为 `unsafe`**,因为任何对裸指针的解引用、转换或地址操作都可能导致未定义行为。
/// 使用前,调用者**必须**确保:
///
/// * 指针所指向的内存区域在解引用时是**有效**的(已分配、未释放、且对齐正确)。
/// * 若进行可变操作(`as_mut_ptr`、`deref_mut`),则必须保证不存在其它并发访问(包括读写),
/// 除非使用了外部同步机制(如 `Mutex`、`RwLock`、原子操作等)。
/// * 若跨线程传递,调用者需自行保证数据在线程间的**同步**,避免数据竞争和悬垂指针。
/// * 指针不可为空(`null`),除非调用者明确将其用作标记且从不解引用。
/// * 生命周期必须由调用者手动维护:确保在解引用时原始数据依然存活,且未发生 `move` 或 `drop`。
/// * 泛型参数 `T` 必须与指针实际指向的类型完全匹配,否则转换或解引用将导致立即未定义行为。
///
/// # `Send` 与 `Sync`
/// 该类型本身仅含有一个指针(机器字长),因此类型层面可自动满足 `Send` 和 `Sync`。
/// 但**这绝不意味着所指向的数据也是 `Send`/`Sync`**。调用者必须确保跨线程使用时,
/// 指针指向的数据符合相应的线程安全要求(例如使用 `Arc<Mutex<T>>` 或确保 `T: Send + Sync`)。
///
/// # 示例
/// ```
/// use std::thread;
/// use array_viewer::unsafe_pointer::UnsafePointerHandler;
///
/// let mut value = 42;
/// // 从可变指针创建处理器
/// let handler = unsafe { UnsafePointerHandler::from_mut_ptr(&mut value) };
///
/// let handle = thread::spawn(move || {
/// unsafe {
/// // 在新线程中获取可变引用并修改
/// let mut_ref = handler.deref_mut();
/// *mut_ref += 1;
/// }
/// });
/// handle.join().unwrap();
///
/// // 主线程等待子线程结束,确保 value 在访问期间存活
/// assert_eq!(value, 43);
///
/// // 注意:若子线程在 value 生命周期外访问,将导致悬垂指针,调用者需自行避免。
/// ```
;
// 显式实现 Send 和 Sync(虽然编译器可能自动推导,但我们明确声明以强调意图)
// 安全性:该包装本身仅包含一个指针,可安全在线程间传递,但数据安全性由调用者保证。
unsafe
unsafe