Skip to main content

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}