inplace_init/init.rs
1use core::{
2 convert::Infallible,
3 marker::PhantomData,
4 mem::ManuallyDrop,
5 ops::{Deref, DerefMut},
6 pin::Pin,
7 ptr,
8};
9
10mod defaults;
11mod fields;
12mod initializer;
13
14pub use defaults::{InitDefault, InitDefaultInit, InitDefaultValue};
15pub use fields::{
16 InitField, InitFieldInit, InitFields, InitState, InitTargetPointer, MovableField, PinnedField,
17 Set, Unset,
18};
19pub use initializer::{
20 InitFn, InitFnRaw, InitTyBool, InitTyChar, InitTyI8, InitTyI16, InitTyI32, InitTyI64,
21 InitTyI128, InitTyIsize, InitTyU8, InitTyU16, InitTyU32, InitTyU64, InitTyU128, InitTyUsize,
22 MapInitError,
23};
24
25/// 普通初始化的地址模式;初始化完成后,值可从其存储位置移出。
26/// Marker for movable initialization; after initialization, the value may be moved out of its storage.
27pub struct InitMode;
28
29/// 固定地址初始化的模式标记;初始化器必须在目标的最终地址构造值。
30/// Marker for pinned initialization; the initializer must construct the value at its final address.
31pub struct PinInitMode;
32
33/// 独占一个未初始化目标地址的一次性凭证。
34/// A one-use token that exclusively owns an uninitialized target address.
35///
36/// 槽位携带目标的独占借用;成功初始化后必须消费它并取得 [`InitReceipt`]。
37/// The slot carries an exclusive borrow of the target; successful initialization consumes it and yields an [`InitReceipt`].
38pub struct InitSlot<'slot, T, Mode = InitMode> {
39 pointer: *mut T,
40 _borrow: PhantomData<&'slot mut T>,
41 _mode: PhantomData<fn() -> Mode>,
42}
43
44impl<'slot, T, Mode> InitSlot<'slot, T, Mode> {
45 /// 将完整值写入目标存储,并返回负责析构该值的凭证。
46 /// Write a complete value into the target storage and return the receipt that owns its destruction.
47 pub fn write(self, value: T) -> InitReceipt<'slot, T, Mode> {
48 // 安全性:槽位仅由有效未初始化存储的独占入口创建。 Safety: a slot is created only from exclusive access to valid, uninitialized storage.
49 unsafe { self.pointer.write(value) };
50 // 安全性:上一步已在槽位地址完整构造一个 T。 Safety: the previous write fully constructed a T at the slot address.
51 unsafe { InitReceipt::new(self.pointer) }
52 }
53
54 /// 使用目标类型为当前地址模式提供的默认实现构造值。
55 /// Construct a value using the target type's default initializer for the current address mode.
56 pub fn initialize_default(self) -> InitReceipt<'slot, T, Mode>
57 where
58 T: InitDefault<T, Mode>,
59 {
60 T::initialize_default(self)
61 }
62
63 /// 返回目标的原始地址,供派生宏生成的字段投影代码使用。
64 /// Return the target's raw address for field-projection code generated by the derive macro.
65 #[doc(hidden)]
66 pub fn __target_ptr(&self) -> *mut T {
67 self.pointer
68 }
69
70 /// 返回目标的原始可变地址,供高级原始地址初始化适配器使用。
71 /// Return the target's raw mutable address for advanced raw-pointer initializer adapters.
72 #[doc(hidden)]
73 pub fn __raw_mut_ptr(&self) -> *mut T {
74 self.pointer
75 }
76
77 /// 为父目标中的一个独占字段创建一次性槽位。
78 /// Create a one-use slot for an exclusive field within the parent target.
79 ///
80 /// # 安全性要求
81 /// `pointer` 必须指向父目标中有效、对齐且尚未初始化的字段,且不得与仍在使用的其他字段槽位重叠。
82 ///
83 /// # Safety
84 /// `pointer` must point to a valid, aligned, uninitialized field in the parent target and must not overlap another field slot that is still in use.
85 #[doc(hidden)]
86 pub unsafe fn __project<U>(&mut self, pointer: *mut U) -> InitSlot<'slot, U, Mode> {
87 InitSlot {
88 pointer,
89 _borrow: PhantomData,
90 _mode: PhantomData,
91 }
92 }
93
94 /// 将字段槽位重新标记为另一地址模式。
95 /// Retag a field slot with another address mode.
96 ///
97 /// # 安全性要求
98 /// 调用方必须确保新模式不会让初始化器违反目标字段的固定约束;派生代码仅对未标记 `#[pin]` 的字段使用此入口。
99 ///
100 /// # Safety
101 /// The caller must ensure that the new mode cannot violate the field's pinning invariants; derive code uses this only for fields without `#[pin]`.
102 #[doc(hidden)]
103 pub unsafe fn __retag<Other>(self) -> InitSlot<'slot, T, Other> {
104 InitSlot {
105 pointer: self.pointer,
106 _borrow: PhantomData,
107 _mode: PhantomData,
108 }
109 }
110
111 /// 将已完整构造的目标转换为析构凭证。
112 /// Convert a fully constructed target into its destruction receipt.
113 ///
114 /// # 安全性要求
115 /// 调用方必须先在目标地址完整构造有效的 `T`,并确保它满足 `Mode` 的地址保证。
116 ///
117 /// # Safety
118 /// The caller must first fully construct a valid `T` at the target address and uphold the address guarantees of `Mode`.
119 #[doc(hidden)]
120 pub unsafe fn __assume_init(self) -> InitReceipt<'slot, T, Mode> {
121 // 安全性:由调用方保证目标已经完整初始化。 Safety: the caller guarantees that the target is fully initialized.
122 unsafe { InitReceipt::new(self.pointer) }
123 }
124
125 /// 从受控的原始存储创建槽位。
126 /// Create a slot from storage whose validity is established by the caller.
127 ///
128 /// # 安全性要求
129 /// `pointer` 必须指向有效、对齐且未初始化的 `T` 存储,并在槽位及后续凭证存活期间保持有效。
130 ///
131 /// # Safety
132 /// `pointer` must point to valid, aligned, uninitialized storage for `T` and remain valid while the slot and any resulting receipt exist.
133 #[doc(hidden)]
134 pub unsafe fn __from_raw(pointer: *mut T) -> Self {
135 Self {
136 pointer,
137 _borrow: PhantomData,
138 _mode: PhantomData,
139 }
140 }
141}
142
143/// 独占已初始化值及其析构责任的凭证。
144/// A receipt that exclusively owns an initialized value and responsibility for dropping it.
145///
146/// 凭证被销毁时会析构目标;普通模式可移出值,固定模式只能通过 `Pin` 借用。
147/// Dropping the receipt drops the target; movable mode can extract the value, while pinned mode exposes only `Pin` borrows.
148pub struct InitReceipt<'slot, T, Mode = InitMode> {
149 pointer: *mut T,
150 _borrow: PhantomData<&'slot mut T>,
151 _mode: PhantomData<fn() -> Mode>,
152}
153
154impl<'slot, T, Mode> InitReceipt<'slot, T, Mode> {
155 /// 为已初始化目标创建唯一析构凭证。
156 /// Create the unique destruction receipt for an initialized target.
157 /// # Safety
158 /// `pointer` 必须指向有效且已初始化的 `T`,并且本凭证必须独占其析构责任。
159 /// The pointer must refer to a valid initialized `T`, and this receipt must be the sole owner of its destruction responsibility.
160 pub(crate) unsafe fn new(pointer: *mut T) -> Self {
161 Self {
162 pointer,
163 _borrow: PhantomData,
164 _mode: PhantomData,
165 }
166 }
167
168 /// 将凭证转换为另一地址模式。
169 /// Retag the receipt with another address mode.
170 ///
171 /// # Safety
172 /// 调用方必须证明转换后的模式仍满足目标值的地址约束,且转换期间没有其他
173 /// 凭证持有该值的析构责任。
174 /// The caller must prove that the new mode still satisfies the value's address invariants and that no other receipt owns its destruction responsibility.
175 #[doc(hidden)]
176 pub unsafe fn __retag<Other>(self) -> InitReceipt<'slot, T, Other> {
177 let receipt = ManuallyDrop::new(self);
178 // 安全性:调用方保证新模式合法;ManuallyDrop 转移唯一析构责任。 Safety: the caller validates the new mode, and ManuallyDrop transfers the sole drop responsibility.
179 unsafe { InitReceipt::new(receipt.pointer) }
180 }
181}
182
183impl<T, Mode> Deref for InitReceipt<'_, T, Mode> {
184 type Target = T;
185
186 fn deref(&self) -> &Self::Target {
187 // 安全性:凭证仅在初始化成功后创建,并独占目标值。 Safety: a receipt is created only after successful initialization and exclusively owns the target value.
188 unsafe { &*self.pointer }
189 }
190}
191
192impl<T> DerefMut for InitReceipt<'_, T, InitMode> {
193 fn deref_mut(&mut self) -> &mut Self::Target {
194 // 安全性:普通模式凭证的独占借用允许访问可移动目标。 Safety: the exclusive borrow held by a movable-mode receipt permits mutable access to its target.
195 unsafe { &mut *self.pointer }
196 }
197}
198
199impl<T> InitReceipt<'_, T, InitMode> {
200 /// 将普通值从其存储地址移出,并转移其所有权给调用方。
201 /// Move a value out of its storage and transfer ownership to the caller.
202 pub fn into_inner(self) -> T {
203 let receipt = ManuallyDrop::new(self);
204 // 安全性:普通模式允许移动值;ManuallyDrop 防止源地址再次析构。 Safety: movable mode permits extraction, and ManuallyDrop prevents the source address from being dropped again.
205 unsafe { receipt.pointer.read() }
206 }
207}
208
209impl<T> InitReceipt<'_, T, PinInitMode> {
210 /// 获取已固定值的共享固定借用。
211 /// Obtain a shared pinned borrow of the initialized value.
212 pub fn as_pin_ref(&self) -> Pin<&T> {
213 // 安全性:PinInitMode 仅由固定初始化入口创建。 Safety: PinInitMode is created only by pinned initialization entry points.
214 unsafe { Pin::new_unchecked(&*self.pointer) }
215 }
216
217 /// 获取已固定值的可变固定借用。
218 /// Obtain an exclusive pinned borrow of the initialized value.
219 pub fn as_pin_mut(&mut self) -> Pin<&mut T> {
220 // 安全性:凭证独占目标,且 PinInitMode 保证目标地址稳定。 Safety: the receipt exclusively borrows the target, and PinInitMode guarantees its address remains stable.
221 unsafe { Pin::new_unchecked(&mut *self.pointer) }
222 }
223}
224
225impl<T, Mode> Drop for InitReceipt<'_, T, Mode> {
226 fn drop(&mut self) {
227 // 安全性:凭证唯一拥有目标值的析构责任。 Safety: the receipt is the sole owner of the target's destruction responsibility.
228 unsafe { ptr::drop_in_place(self.pointer) };
229 }
230}
231
232/// 在一次性槽位中构造一个值。
233/// An initializer that constructs a value in a one-use target slot.
234///
235/// 错误类型与地址模式由 trait 参数表达;只有成功时才会返回析构凭证。
236/// The error type and address mode are expressed by trait parameters; a destruction receipt is returned only on success.
237///
238/// # 安全性
239/// 实现必须满足以下所有条件:
240///
241/// - 成功时恰好构造一个有效的 `T`,返回的凭证是该值唯一的析构责任拥有者。
242/// - 返回 `Err` 或展开 panic 时,必须销毁所有已构造的完整值和部分字段,使槽位保持未初始化;不得留下未被有效凭证跟踪的已初始化状态。
243/// - 初始化多个字段时,必须保留已完成字段的凭证,直到后续字段也完成;只有全部字段成功后,才能消费字段凭证并创建整体凭证。
244/// - 必须满足 `Mode` 对目标地址的约束。
245///
246/// # Safety
247/// Implementations must satisfy all of the following:
248///
249/// - On success, construct exactly one valid `T`, and return the sole receipt responsible for dropping it.
250/// - On `Err` or panic unwinding, drop every constructed value and partial field, leaving the slot uninitialized; no initialized state may remain without a valid receipt tracking it.
251/// - When initializing multiple fields, retain receipts for completed fields until all later fields succeed. Consume those receipts and create the whole-value receipt only after every field succeeds.
252/// - Uphold the target-address requirements of `Mode`.
253pub unsafe trait Init<T, E = Infallible, Mode = InitMode>: Sized {
254 /// 消耗目标槽位并返回已初始化值的析构凭证。
255 /// Consume the target slot and return a destruction receipt for the initialized value.
256 fn initialize<'slot>(
257 self,
258 slot: InitSlot<'slot, T, Mode>,
259 ) -> Result<InitReceipt<'slot, T, Mode>, E>;
260
261 /// 将初始化器的错误映射为另一种错误类型,同时保留地址模式。
262 /// Map the initializer's error to another type while preserving its address mode.
263 ///
264 /// 成功时不会调用映射闭包;闭包会随初始化器结果一同释放。
265 /// The mapping closure is not called on success and is dropped with the completed initializer.
266 fn map_err<F, E2>(self, map: F) -> MapInitError<Self, F, E, Mode>
267 where
268 Self: Sized,
269 F: FnOnce(E) -> E2,
270 {
271 MapInitError::<Self, F, E, Mode>::new(self, map)
272 }
273}
274
275/// 直接操作原始地址的高级初始化器。
276/// An advanced initializer that writes directly through a raw target pointer.
277///
278/// # Safety
279/// 成功时必须恰好构造一个有效的 `T`,且其唯一析构责任应交给 [`RawInit`] 创建的凭证;
280/// 同时满足 `Mode` 的地址保证。返回错误或发生 panic 时,目标存储必须保持未初始化,
281/// 并清理此前已构造的所有完整值和部分状态。
282/// On success, the implementation must construct exactly one valid `T`, transfer its sole
283/// destruction responsibility to the receipt created by [`RawInit`], and uphold `Mode`'s address
284/// guarantees. On error or panic, storage must remain uninitialized and all constructed values
285/// and partial state must be cleaned up.
286pub unsafe trait InitRaw<T, E = Infallible, Mode = InitMode> {
287 /// 在目标存储中构造值。
288 /// Construct a value in the target storage.
289 ///
290 /// # Safety
291 /// `slot` 必须非空、正确对齐,并指向可写入 `T` 大小的未初始化存储。
292 /// `slot` must be non-null, properly aligned, writable, and point to uninitialized storage large enough for `T`.
293 unsafe fn init_raw(self, slot: *mut T) -> Result<(), E>;
294}
295
296/// 将高级原始地址初始化器接入安全初始化入口。
297/// Adapts an advanced raw-pointer initializer to the safe [`Init`] interface.
298pub struct RawInit<I> {
299 initializer: I,
300}
301
302impl<I> RawInit<I> {
303 /// 包装一个实现了 [`InitRaw`] 的初始化器。
304 /// Wrap an initializer that implements [`InitRaw`].
305 pub const fn new(initializer: I) -> Self {
306 Self { initializer }
307 }
308}
309
310// 安全性依据:InitRaw 的 unsafe 契约保证失败时清理且成功时恰好构造一个完整目标;本适配器只在成功后创建整体凭证。
311// Safety: InitRaw's unsafe contract guarantees cleanup on failure and exactly one complete target on success; this adapter creates the whole-value receipt only after success.
312unsafe impl<T, E, Mode, I> Init<T, E, Mode> for RawInit<I>
313where
314 I: InitRaw<T, E, Mode>,
315{
316 fn initialize<'slot>(
317 self,
318 slot: InitSlot<'slot, T, Mode>,
319 ) -> Result<InitReceipt<'slot, T, Mode>, E> {
320 // 安全性:InitRaw 契约要求错误或 panic 时清理部分状态。 Safety: InitRaw's contract requires partial state to be cleaned up on error or panic.
321 unsafe { self.initializer.init_raw(slot.__raw_mut_ptr())? };
322 // 安全性:InitRaw 成功返回时已完整构造满足模式约束的 T。 Safety: a successful InitRaw return means a complete T satisfying the mode invariants exists.
323 Ok(unsafe { slot.__assume_init() })
324 }
325}