pin-init/src/lib.rs

10 //! This library's main use-case is in [Rust-for-Linux]. Although this version can be used
53 //! Throughout the examples we will often make use of the `CMutex` type which can be found in
60 //! If you want to use [`PinInit`], then you will have to annotate your `struct` with
69 //! # #[path = "../examples/mutex.rs"] mod mutex; use mutex::*;
70 //! # use core::pin::Pin;
71 //! use pin_init::{pin_data, pin_init, InPlaceInit};
87 //! `foo` now is of the type [`impl PinInit<Foo>`]. We can now use any smart pointer that we like
93 //! # #[path = "../examples/mutex.rs"] mod mutex; use mutex::*;
94 //! # use core::{alloc::AllocError, pin::Pin};
95 //! # use pin_init::*;
115 //! Many types that use this library supply a function/macro that returns an initializer, because
120 //! # #[path = "../examples/mutex.rs"] mod mutex; use mutex::*;
121 //! # use pin_init::*;
122 //! # use std::sync::Arc;
123 //! # use core::pin::Pin;
131 //! # use pin_init::*;
132 //! # #[path = "../examples/error.rs"] mod error; use error::Error;
133 //! # #[path = "../examples/mutex.rs"] mod mutex; use mutex::*;
167 //! use pin_init::{pin_data, pinned_drop, PinInit, PinnedDrop, pin_init_from_closure};
168 //! use core::{
238 //! For more information on how to use [`pin_init_from_closure()`], take a look at the uses inside
273 use core::{
291 pub use alloc::InPlaceInit;
300 /// This macro enables the use of the [`pin_init!`] macro. When pin-initializing a `struct`,
311 /// # #[path = "../examples/mutex.rs"] mod mutex; use mutex::*;
312 /// use pin_init::pin_data;
328 /// # #[path = "../examples/mutex.rs"] mod mutex; use mutex::*;
330 /// use core::pin::Pin;
331 /// use pin_init::{pin_data, pinned_drop, PinnedDrop};
352 pub use ::pin_init_internal::pin_data;
362 /// # #[path = "../examples/mutex.rs"] mod mutex; use mutex::*;
364 /// use core::pin::Pin;
365 /// use pin_init::{pin_data, pinned_drop, PinnedDrop};
386 pub use ::pin_init_internal::pinned_drop;
395 /// use pin_init::Zeroable;
404 pub use ::pin_init_internal::Zeroable;
413 /// # #[path = "../examples/mutex.rs"] mod mutex; use mutex::*;
414 /// # use pin_init::*;
415 /// # use core::pin::Pin;
441 /// [`PinInit`]/[`Init`] with the error type [`Infallible`]. If you want to use a different error
442 /// type, then use [`stack_try_pin_init!`].
465 /// # #[path = "../examples/error.rs"] mod error; use error::Error;
466 /// # #[path = "../examples/mutex.rs"] mod mutex; use mutex::*;
467 /// # use pin_init::*;
492 /// # #[path = "../examples/error.rs"] mod error; use error::Error;
493 /// # #[path = "../examples/mutex.rs"] mod mutex; use mutex::*;
494 /// # use pin_init::*;
537 /// This macro defaults the error to [`Infallible`]. If you need a different error, then use
543 /// # use pin_init::*;
544 /// # use core::pin::Pin;
587 /// # use pin_init::*;
588 /// # use core::pin::Pin;
614 /// # use pin_init::*;
615 /// # use core::pin::Pin;
641 /// # use pin_init::*;
642 /// # use core::pin::Pin;
690 /// - Fields that you want to initialize in-place have to use `<-` instead of `:`.
700 /// # use pin_init::*;
701 /// # use core::{ptr::addr_of_mut, marker::PhantomPinned};
740 /// If the initialization can complete without error (or [`Infallible`]), then use [`pin_init!`].
742 /// You can use the `?` operator or use `return Err(err)` inside the initializer to stop
749 /// after the `struct` initializer to specify the error type you want to use.
755 /// # #[path = "../examples/error.rs"] mod error; use error::Error;
756 /// use pin_init::{pin_data, try_pin_init, PinInit, InPlaceInit, zeroed};
798 /// This macro defaults the error to [`Infallible`]. If you need a different error, then use
808 /// pin-initialize, use [`pin_init!`].
814 /// # #[path = "../examples/error.rs"] mod error; use error::Error;
815 /// # #[path = "../examples/mutex.rs"] mod mutex; use mutex::*;
816 /// # use pin_init::InPlaceInit;
817 /// use pin_init::{init, Init, zeroed};
847 /// If the initialization can complete without error (or [`Infallible`]), then use
862 /// # use core::alloc::AllocError;
863 /// # use pin_init::InPlaceInit;
864 /// use pin_init::{try_init, Init, zeroed};
908 /// use pin_init::{pin_data, assert_pinned};
921 /// use pin_init::{pin_data, assert_pinned};
931 /// Some uses of the macro may trigger the `can't use generic parameters from outer item` error. To
935 /// # use core::pin::Pin;
936 /// use pin_init::{pin_data, assert_pinned};
974 /// To use this initializer, you will need a suitable memory location that can hold a `T`. This can
982 /// cases where a manual implementation is necessary. Use [`pin_init_from_closure`] where possible.
1023     /// # #[path = "../examples/mutex.rs"] mod mutex; use mutex::*;
1024     /// # use pin_init::*;
1066 /// To use this initializer, you will need a suitable memory location that can hold a `T`. This can
1068 /// [`PinInit<T, E>`] is a super trait, you can use every function that takes it as well.
1075 /// cases where a manual implementation is necessary. Use [`init_from_closure`] where possible.
1121     /// use pin_init::{init, zeroed, Init};
1233 /// # use pin_init::*;
1234 /// use pin_init::init_array_from_fn;
1272 /// # #[path = "../examples/mutex.rs"] mod mutex; use mutex::*;
1273 /// # use pin_init::*;
1274 /// # use core::pin::Pin;
1275 /// use pin_init::pin_init_array_from_fn;
1276 /// use std::sync::Arc;
1331     /// Use the given initializer to write a value into `self`.
1336     /// Use the given pin-initializer to write a value into `self`.
1344 /// Use [`pinned_drop`] to implement this trait safely:
1348 /// # #[path = "../examples/mutex.rs"] mod mutex; use mutex::*;
1349 /// # use pin_init::*;
1350 /// use core::pin::Pin;
1459     // We cannot use `T: ?Sized`, since the VTABLE pointer part of fat pointers is not allowed to be
1462     // When `Pointee` gets stabilized, we could use