Struct pin_init::PinUninit [−][src]
pub struct PinUninit<'a, T> { /* fields omitted */ }
Expand description
A pinned, uninitialized pointer.
This can be considered as Pin<&mut MaybeUninit<T>>
:
- The pointee has a stable location in memory. It cannot be moved elsewhere.
- The pointee is not yet initialized, therefore the drop guarantee is not existent.
However, PinUninit
provides the additional guarantee that once a method
that successfully initialze the data is called (e.g. init_ok
), the
pointee will be considered as Pin<&mut T>
, therefore the drop guarantee
kicks in, and T
’s destructor is guaranteed to be called before the storage
is deallocated.
Implementations
Creates a new PinUninit
with a given MaybeUninit<T>
.
Safety
The caller must ensure ptr
has a stable location in memory.
The caller must obtain a InitResult
that is tied to the lifetime of the returned
PinUninit
, and need to respect its value:
- If
InitOk
is obtained, the caller must treat theptr
asPin<&mut T>
. This means that the drop guarantee kick in; the memory cannot be deallocated untilT
is dropped. - If
InitErr
is obtained,ptr
is uninitialized and the caller must not try to dropT
. - If panic happens while trying to get the result, then we are not certain about initialization state. This means that the caller must respect the drop guarantee, but also not drop the value. The only solution is to leak memory. If that’s not possible, then the caller must abort the process.
The lifetime associated with this function should be “closed”. It should be a local,
temporary lifetime, shorter than any of the lifetime the caller have access to (including
'static
, and should not escape the calling function.
This is to guarantee that the only way to get a InitResult<'a, T, E>
is to use of the methods of this particular PinUninit
returned.
In order to satisfy the requirement, the caller typically takes a constructor with type
Init<T, E>
, which can be seen as for<'a> FnOnce(PinUninit<'a, T>) -> InitResult<'a, T, E>
.
Gets a mutable reference to MaybeUninit
inside of this PinUninit
.
This is safe because the MaybeUninit
we point to is not yet initialized,
and MaybeUninit
does not have Drop
implementation.
Asserts that the initialize is indeed completed. Doing so initiates the
drop guarantee of T
.
Safety
This function is unsafe as this is equivalent to MaybeUninit::assume_init
.
Generates a InitResult
signaling that the initialization is failed.
Note that the caller should make sure nothing is partially pinned-initialized.
This isn’t the contract of this function, but is the contract for
creating PinUninit
for pinned-initializing sub-fields.
Completes the initialization with a callback.
Useful e.g. if the callback is produced by init_pin!
.
Completes the initialization by moving the given value.
Useful if the the type T
can be initialized unpinned.