Lines Matching +full:self +full:- +full:working
1 [](https://crates.io/crates/pin-init)
2 [](https://docs.rs/pin-init/)
3 [](https://deps.rs/repo/github/Rust-for-Linux/pin-init)
4 
5 [](#nightly-only)
6 
7 # `pin-init`
11 > This crate was originally named [`pinned-init`], but the migration to
12 > `pin-init` is not yet complete. The `legcay` branch contains the current
13 > version of the `pinned-init` crate & the `main` branch already incorporates
14 > the rename to `pin-init`.
19 [`pinned-init`]: https://crates.io/crates/pinned-init
21 <!-- cargo-rdme start -->
23 Library to safely and fallibly initialize pinned `struct`s using in-place constructors.
27 It also allows in-place initialization of big `struct`s that would otherwise produce a stack
30 This library's main use-case is in [Rust-for-Linux]. Although this version can be used
33 There are cases when you want to in-place initialize a struct. For example when it is very big
38 <https://rust-for-linux.com/the-safe-pinned-initialization-problem>.
40 This library allows you to do in-place initialization safely.
48 [`allocator_api` unstable feature]: https://doc.rust-lang.org/nightly/unstable-book/library-features/allocator-api.html
50 The feature is enabled by default, thus by default `pin-init` will require a nightly compiler.
52 will require the `std` feature, because stable compilers have neither `Box` nor `Arc` in no-std
55 ### Nightly needed for `unsafe-pinned` feature
58 This requires the [`unsafe_pinned` unstable feature](https://github.com/rust-lang/rust/issues/125735)
63 To initialize a `struct` with an in-place constructor you will need two things:
64 - an in-place constructor,
65 - a memory location that can hold your `struct` (this can be the [stack], an [`Arc<T>`],
68 To get an in-place constructor there are generally three options:
69 - directly creating an in-place constructor using the [`pin_init!`] macro,
70 - a custom function/macro returning an in-place constructor provided by someone else,
71 - using the unsafe function [`pin_init_from_closure()`] to manually create an initializer.
73 Aside from pinned initialization, this library also supports in-place construction without
88 [structurally pinned fields]. After doing this, you can then create an in-place constructor via
90 that you need to write `<-` instead of `:` for fields that you want to initialize in-place.
103 a <- CMutex::new(42),
137 fn new() -> impl PinInit<Self, Error> {
138 try_pin_init!(Self {
139 status <- CMutex::new(0),
148 Often when working with primitives the previous approaches are not sufficient. That is where
153 - when the closure returns `Ok(())`, then it has completed the initialization successfully, so
155 - when the closure returns `Err(e)`, then the caller may deallocate the memory at `slot`, so
156 you need to take care to clean up anything if your initialization fails mid-way,
157 - you may assume that `slot` will stay pinned even after the closure returns until `drop` of
178 pub fn enable_foo(ptr: *mut foo, flags: u32) -> i32;
194 pub fn new(flags: u32) -> impl PinInit<Self, i32> {
196 // - when the closure returns `Ok(())`, then it has successfully initialized and
198 // - when it returns `Err(e)`, then it has cleaned up before
200 pin_init_from_closure(move |slot: *mut Self| {
225 fn drop(self: Pin<&mut Self>) {
227 unsafe { bindings::destroy_foo(self.foo.get().cast::<bindings::foo>()) };
236 [pinning]: https://doc.rust-lang.org/std/pin/index.html
237 [structurally pinned fields]: https://doc.rust-lang.org/std/pin/index.html#projections-and-structural-pinning
238 [stack]: https://docs.rs/pin-init/latest/pin_init/macro.stack_pin_init.html
239 [`impl PinInit<Foo>`]: https://docs.rs/pin-init/latest/pin_init/trait.PinInit.html
240 [`impl PinInit<T, E>`]: https://docs.rs/pin-init/latest/pin_init/trait.PinInit.html
241 [`impl Init<T, E>`]: https://docs.rs/pin-init/latest/pin_init/trait.Init.html
242 [Rust-for-Linux]: https://rust-for-linux.com/
244 <!-- cargo-rdme end -->
246 <!-- These links are not picked up by cargo-rdme, since they are behind cfgs... -->
247 [`Arc<T>`]: https://doc.rust-lang.org/stable/alloc/sync/struct.Arc.html
248 [`Box<T>`]: https://doc.rust-lang.org/stable/alloc/boxed/struct.Box.html