1 // SPDX-License-Identifier: Apache-2.0 OR MIT
3 //! API to safely and fallibly initialize pinned `struct`s using in-place constructors.
5 //! It also allows in-place initialization of big `struct`s that would otherwise produce a stack
8 //! Most `struct`s from the [`sync`] module need to be pinned, because they contain self-referential
13 //! To initialize a `struct` with an in-place constructor you will need two things:
14 //! - an in-place constructor,
15 //! - a memory location that can hold your `struct` (this can be the [stack], an [`Arc<T>`],
18 //! To get an in-place constructor there are generally three options:
19 //! - directly creating an in-place constructor using the [`pin_init!`] macro,
20 //! - a custom function/macro returning an in-place constructor provided by someone else,
21 //! - using the unsafe function [`pin_init_from_closure()`] to manually create an initializer.
23 //! Aside from pinned initialization, this API also supports in-place construction without pinning,
33 //! [structurally pinned fields]. After doing this, you can then create an in-place constructor via
35 //! that you need to write `<-` instead of `:` for fields that you want to initialize in-place.
42 //! struct Foo {
48 //! let foo = pin_init!(Foo {
49 //!     a <- new_mutex!(42, "Foo::a"),
54 //! `foo` now is of the type [`impl PinInit<Foo>`]. We can now use any smart pointer that we like
55 //! (or just the stack) to actually initialize a `Foo`:
62 //! # struct Foo {
67 //! # let foo = pin_init!(Foo {
68 //! #     a <- new_mutex!(42, "Foo::a"),
71 //! let foo: Result<Pin<Box<Foo>>> = Box::pin_init(foo);
99 //!     fn new() -> impl PinInit<Self, Error> {
101 //!             status <- new_mutex!(0, "DriverData::status"),
115 //! - when the closure returns `Ok(())`, then it has completed the initialization successfully, so
117 //! - when the closure returns `Err(e)`, then the caller may deallocate the memory at `slot`, so
118 //!   you need to take care to clean up anything if your initialization fails mid-way,
119 //! - you may assume that `slot` will stay pinned even after the closure returns until `drop` of
128 //! #     pub struct foo;
129 //! #     pub unsafe fn init_foo(_ptr: *mut foo) {}
130 //! #     pub unsafe fn destroy_foo(_ptr: *mut foo) {}
131 //! #     pub unsafe fn enable_foo(_ptr: *mut foo, _flags: u32) -> i32 { 0 }
135 //! #     fn from_errno(errno: core::ffi::c_int) -> Error {
143 //! /// `foo` is always initialized
147 //!     foo: Opaque<bindings::foo>,
153 //!     pub fn new(flags: u32) -> impl PinInit<Self, Error> {
155 //!         // - when the closure returns `Ok(())`, then it has successfully initialized and
156 //!         //   enabled `foo`,
157 //!         // - when it returns `Err(e)`, then it has cleaned up before
161 //!                 let foo = addr_of_mut!((*slot).foo);
163 //!                 // Initialize the `foo`
164 //!                 bindings::init_foo(Opaque::raw_get(foo));
167 //!                 let err = bindings::enable_foo(Opaque::raw_get(foo), flags);
169 //!                     // Enabling has failed, first clean up the foo and then return the error.
170 //!                     bindings::destroy_foo(Opaque::raw_get(foo));
184 //!         // SAFETY: Since `foo` is initialized, destroying is safe.
185 //!         unsafe { bindings::destroy_foo(self.foo.get()) };
190 //! For the special case where initializing a field is a single FFI-function call that cannot fail,
199 //! [pinning]: https://doc.rust-lang.org/std/pin/index.html
201 //!     https://doc.rust-lang.org/std/pin/index.html#pinning-is-structural-for-field
204 //! [`impl PinInit<Foo>`]: PinInit
243 /// struct Foo {
246 ///     b: Bar,
250 /// struct Bar {
254 /// stack_pin_init!(let foo = pin_init!(Foo {
255 ///     a <- new_mutex!(42),
256 ///     b: Bar {
260 /// let foo: Pin<&mut Foo> = foo;
261 /// pr_info!("a: {}", &*foo.a.lock());
296 /// struct Foo {
299 ///     b: Box<Bar>,
302 /// struct Bar {
306 /// stack_try_pin_init!(let foo: Result<Pin<&mut Foo>, AllocError> = pin_init!(Foo {
307 ///     a <- new_mutex!(42),
308 ///     b: Box::try_new(Bar {
312 /// let foo = foo.unwrap();
313 /// pr_info!("a: {}", &*foo.a.lock());
322 /// struct Foo {
325 ///     b: Box<Bar>,
328 /// struct Bar {
332 /// stack_try_pin_init!(let foo: Pin<&mut Foo> =? pin_init!(Foo {
333 ///     a <- new_mutex!(42),
334 ///     b: Box::try_new(Bar {
338 /// pr_info!("a: {}", &*foo.a.lock());
361 /// Construct an in-place, pinned initializer for `struct`s.
373 /// struct Foo {
375 ///     b: Bar,
379 /// struct Bar {
383 /// # fn demo() -> impl PinInit<Foo> {
386 /// let initializer = pin_init!(Foo {
388 ///     b: Bar {
404 /// # Init-functions
418 /// # struct Foo {
420 /// #     b: Bar,
423 /// # struct Bar {
426 /// impl Foo {
427 ///     fn new() -> impl PinInit<Self> {
430 ///             b: Bar {
438 /// Users of `Foo` can now create it like this:
445 /// # struct Foo {
447 /// #     b: Bar,
450 /// # struct Bar {
453 /// # impl Foo {
454 /// #     fn new() -> impl PinInit<Self> {
457 /// #             b: Bar {
463 /// let foo = Box::pin_init(Foo::new());
473 /// # struct Foo {
475 /// #     b: Bar,
478 /// # struct Bar {
481 /// # impl Foo {
482 /// #     fn new() -> impl PinInit<Self> {
485 /// #             b: Bar {
494 ///     foo1: Foo,
496 ///     foo2: Foo,
501 ///     fn new(other: u32) -> impl PinInit<Self> {
503 ///             foo1 <- Foo::new(),
504 ///             foo2 <- Foo::new(),
511 /// Here we see that when using `pin_init!` with `PinInit`, one needs to write `<-` instead of `:`.
512 /// This signifies that the given field is initialized in-place. As with `struct` initializers, just
513 /// writing the field (in this case `other`) without `:` or `<-` means `other: other,`.
519 /// - Fields that you want to initialize in-place have to use `<-` instead of `:`.
520 /// - In front of the initializer you can write `&this in` to have access to a [`NonNull<Self>`]
522 /// - Using struct update syntax one can place `..Zeroable::zeroed()` at the very end of the
573 /// Construct an in-place, fallible pinned initializer for `struct`s.
601 ///     fn new() -> impl PinInit<Self, Error> {
644 /// Construct an in-place initializer for `struct`s.
650 /// - `unsafe` code must guarantee either full initialization or return an error and allow
652 /// - the fields are initialized in the order given in the initializer.
653 /// - no references to fields are allowed to be created inside of the initializer.
655 /// This initializer is for initializing data in-place that might later be moved. If you want to
656 /// pin-initialize, use [`pin_init!`].
679 /// Construct an in-place fallible initializer for `struct`s.
687 /// - `unsafe` code must guarantee either full initialization or return an error and allow
689 /// - the fields are initialized in the order given in the initializer.
690 /// - no references to fields are allowed to be created inside of the initializer.
702 ///     fn new() -> impl Init<Self, Error> {
744 /// A pin-initializer for the type `T`.
758 /// - returns `Ok(())` if it initialized every field of `slot`,
759 /// - returns `Err(err)` if it encountered an error and then cleaned `slot`, this means:
760 ///     - `slot` can be deallocated without UB occurring,
761 ///     - `slot` does not need to be dropped,
762 ///     - `slot` is not partially initialized.
763 /// - while constructing the `T` at `slot` it upholds the pinning invariants of `T`.
773     /// - `slot` is a valid pointer to uninitialized memory.
774     /// - the caller does not touch `slot` when `Err` is returned, they are only permitted to
776     /// - `slot` will not move until it is dropped, i.e. it will be pinned.
777     unsafe fn __pinned_init(self, slot: *mut T) -> Result<(), E>;  in __pinned_init()
796     /// struct Foo {
801     /// impl Foo {
803     ///         pr_info!("Setting up foo");
807     /// let foo = pin_init!(Foo {
808     ///     raw <- unsafe {
813     /// }).pin_chain(|foo| {
814     ///     foo.setup();
818     fn pin_chain<F>(self, f: F) -> ChainPinInit<Self, F, T, E>  in pin_chain()
820         F: FnOnce(Pin<&mut T>) -> Result<(), E>,  in pin_chain()
830 // - returns `Ok(())` on successful initialization,
831 // - returns `Err(err)` on error and in this case `slot` will be dropped.
832 // - considers `slot` pinned.
836     F: FnOnce(Pin<&mut T>) -> Result<(), E>,
838     unsafe fn __pinned_init(self, slot: *mut T) -> Result<(), E> {  in __pinned_init()
868 /// - returns `Ok(())` if it initialized every field of `slot`,
869 /// - returns `Err(err)` if it encountered an error and then cleaned `slot`, this means:
870 ///     - `slot` can be deallocated without UB occurring,
871 ///     - `slot` does not need to be dropped,
872 ///     - `slot` is not partially initialized.
873 /// - while constructing the `T` at `slot` it upholds the pinning invariants of `T`.
888     /// - `slot` is a valid pointer to uninitialized memory.
889     /// - the caller does not touch `slot` when `Err` is returned, they are only permitted to
891     unsafe fn __init(self, slot: *mut T) -> Result<(), E>;  in __init()
903     /// struct Foo {
907     /// impl Foo {
909     ///         pr_info!("Setting up foo");
913     /// let foo = init!(Foo {
914     ///     buf <- init::zeroed()
915     /// }).chain(|foo| {
916     ///     foo.setup();
920     fn chain<F>(self, f: F) -> ChainInit<Self, F, T, E>  in chain()
922         F: FnOnce(&mut T) -> Result<(), E>,  in chain()
932 // - returns `Ok(())` on successful initialization,
933 // - returns `Err(err)` on error and in this case `slot` will be dropped.
937     F: FnOnce(&mut T) -> Result<(), E>,
939     unsafe fn __init(self, slot: *mut T) -> Result<(), E> {  in __init()
955     F: FnOnce(&mut T) -> Result<(), E>,
957     unsafe fn __pinned_init(self, slot: *mut T) -> Result<(), E> {  in __pinned_init()
968 /// - returns `Ok(())` if it initialized every field of `slot`,
969 /// - returns `Err(err)` if it encountered an error and then cleaned `slot`, this means:
970 ///     - `slot` can be deallocated without UB occurring,
971 ///     - `slot` does not need to be dropped,
972 ///     - `slot` is not partially initialized.
973 /// - may assume that the `slot` does not move if `T: !Unpin`,
974 /// - while constructing the `T` at `slot` it upholds the pinning invariants of `T`.
977     f: impl FnOnce(*mut T) -> Result<(), E>,  in pin_init_from_closure()
978 ) -> impl PinInit<T, E> {  in pin_init_from_closure()
987 /// - returns `Ok(())` if it initialized every field of `slot`,
988 /// - returns `Err(err)` if it encountered an error and then cleaned `slot`, this means:
989 ///     - `slot` can be deallocated without UB occurring,
990 ///     - `slot` does not need to be dropped,
991 ///     - `slot` is not partially initialized.
992 /// - the `slot` may move after initialization.
993 /// - while constructing the `T` at `slot` it upholds the pinning invariants of `T`.
996     f: impl FnOnce(*mut T) -> Result<(), E>,  in init_from_closure()
997 ) -> impl Init<T, E> {  in init_from_closure()
1003 /// The initializer is a no-op. The `slot` memory is not changed.
1005 pub fn uninit<T, E>() -> impl Init<MaybeUninit<T>, E> {  in uninit()
1020     mut make_init: impl FnMut(usize) -> I,  in init_array_from_fn()
1021 ) -> impl Init<[T; N], E>  in init_array_from_fn()
1064     mut make_init: impl FnMut(usize) -> I,  in pin_init_array_from_fn()
1065 ) -> impl PinInit<[T; N], E>  in pin_init_array_from_fn()
1097 // SAFETY: Every type can be initialized by-value.
1099     unsafe fn __init(self, slot: *mut T) -> Result<(), E> {  in __init()
1105 // SAFETY: Every type can be initialized by-value. `__pinned_init` calls `__init`.
1107     unsafe fn __pinned_init(self, slot: *mut T) -> Result<(), E> {  in __pinned_init()
1112 /// Smart pointer that can initialize memory in-place.
1114     /// Use the given pin-initializer to pin-initialize a `T` inside of a new smart pointer of this
1118     fn try_pin_init<E>(init: impl PinInit<T, E>) -> Result<Pin<Self>, E>  in try_pin_init()
1122     /// Use the given pin-initializer to pin-initialize a `T` inside of a new smart pointer of this
1126     fn pin_init<E>(init: impl PinInit<T, E>) -> error::Result<Pin<Self>>  in pin_init()
1137     /// Use the given initializer to in-place initialize a `T`.
1138     fn try_init<E>(init: impl Init<T, E>) -> Result<Self, E>  in try_init()
1142     /// Use the given initializer to in-place initialize a `T`.
1143     fn init<E>(init: impl Init<T, E>) -> error::Result<Self>  in init()
1157     fn try_pin_init<E>(init: impl PinInit<T, E>) -> Result<Pin<Self>, E>  in try_pin_init()
1171     fn try_init<E>(init: impl Init<T, E>) -> Result<Self, E>  in try_init()
1187     fn try_pin_init<E>(init: impl PinInit<T, E>) -> Result<Pin<Self>, E>  in try_pin_init()
1201     fn try_init<E>(init: impl Init<T, E>) -> Result<Self, E>  in try_init()
1224 /// struct Foo {
1230 /// impl PinnedDrop for Foo {
1232 ///         pr_info!("Foo is being dropped!");
1239 /// This trait must be implemented via the [`pinned_drop`] proc-macro attribute on the impl.
1249     /// This extra parameter will be generated by the `#[pinned_drop]` proc-macro attribute
1270 pub fn zeroed<T: Zeroable>() -> impl Init<T> {  in zeroed()