rust/pin-init/README.md

1 [![Crates.io](https://img.shields.io/crates/v/pin-init.svg)](https://crates.io/crates/pin-init)
2 [![Documentation](https://docs.rs/pin-init/badge.svg)](https://docs.rs/pin-init/)
3 …us](https://deps.rs/repo/github/Rust-for-Linux/pin-init/status.svg)](https://deps.rs/repo/github/R…
4 ![License](https://img.shields.io/crates/l/pin-init)
5 [![Toolchain](https://img.shields.io/badge/toolchain-nightly-red)](#nightly-only)
6 ![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/Rust-for-Linux/pin-…
7 # `pin-init`
9 <!-- cargo-rdme start -->
11 Library to safely and fallibly initialize pinned `struct`s using in-place constructors.
15 It also allows in-place initialization of big `struct`s that would otherwise produce a stack
18 This library's main use-case is in [Rust-for-Linux]. Although this version can be used
21 There are cases when you want to in-place initialize a struct. For example when it is very big
26 <https://rust-for-linux.com/the-safe-pinned-initialization-problem>.
28 This library allows you to do in-place initialization safely.
36 …ocator_api` unstable feature]: https://doc.rust-lang.org/nightly/unstable-book/library-features/al…
38 The feature is enabled by default, thus by default `pin-init` will require a nightly compiler.
40 will require the `std` feature, because stable compilers have neither `Box` nor `Arc` in no-std
45 To initialize a `struct` with an in-place constructor you will need two things:
46 - an in-place constructor,
47 - a memory location that can hold your `struct` (this can be the [stack], an [`Arc<T>`],
50 To get an in-place constructor there are generally three options:
51 - directly creating an in-place constructor using the [`pin_init!`] macro,
52 - a custom function/macro returning an in-place constructor provided by someone else,
53 - using the unsafe function [`pin_init_from_closure()`] to manually create an initializer.
55 Aside from pinned initialization, this library also supports in-place construction without
70 [structurally pinned fields]. After doing this, you can then create an in-place constructor via
72 that you need to write `<-` instead of `:` for fields that you want to initialize in-place.
85     a <- CMutex::new(42),
119     fn new() -> impl PinInit<Self, Error> {
121             status <- CMutex::new(0),
135 - when the closure returns `Ok(())`, then it has completed the initialization successfully, so
137 - when the closure returns `Err(e)`, then the caller may deallocate the memory at `slot`, so
138   you need to take care to clean up anything if your initialization fails mid-way,
139 - you may assume that `slot` will stay pinned even after the closure returns until `drop` of
160         pub fn enable_foo(ptr: *mut foo, flags: u32) -> i32;
176     pub fn new(flags: u32) -> impl PinInit<Self, i32> {
178         // - when the closure returns `Ok(())`, then it has successfully initialized and
180         // - when it returns `Err(e)`, then it has cleaned up before
190                 // Try to enable it.
217 [`sync`]: https://rust.docs.kernel.org/kernel/sync/index.html
218 [pinning]: https://doc.rust-lang.org/std/pin/index.html
219 [structurally pinned fields]: https://doc.rust-lang.org/std/pin/index.html#pinning-is-structural-fo…
220 [stack]: https://docs.rs/pin-init/latest/pin_init/macro.stack_pin_init.html
221 [`Arc<T>`]: https://doc.rust-lang.org/stable/alloc/sync/struct.Arc.html
222 [`Box<T>`]: https://doc.rust-lang.org/stable/alloc/boxed/struct.Box.html
223 [`impl PinInit<Foo>`]: https://docs.rs/pin-init/latest/pin_init/trait.PinInit.html
224 [`impl PinInit<T, E>`]: https://docs.rs/pin-init/latest/pin_init/trait.PinInit.html
225 [`impl Init<T, E>`]: https://docs.rs/pin-init/latest/pin_init/trait.Init.html
226 [Rust-for-Linux]: https://rust-for-linux.com/
228 <!-- cargo-rdme end -->