rust/pin-init/src/lib.rs

Source file repositories/reference/linux-study-clean/rust/pin-init/src/lib.rs

File Facts

System
Linux kernel
Corpus path
rust/pin-init/src/lib.rs
Extension
.rs
Size
59290 bytes
Lines
1751
Domain
Rust Kernel Layer
Bucket
Rust API Membrane
Inferred role
Rust Kernel Layer: implementation source
Status
source implementation candidate

Why This File Exists

Rust-side wrappers and abstractions around kernel C APIs, ownership contracts, allocation, synchronization, and module integration.

Dependency Surface

Detected Declarations

Annotated Snippet

// SPDX-License-Identifier: Apache-2.0 OR MIT

//! Library to safely and fallibly initialize pinned `struct`s using in-place constructors.
//!
//! [Pinning][pinning] is Rust's way of ensuring data does not move.
//!
//! It also allows in-place initialization of big `struct`s that would otherwise produce a stack
//! overflow.
//!
//! This library's main use-case is in [Rust-for-Linux]. Although this version can be used
//! standalone.
//!
//! There are cases when you want to in-place initialize a struct. For example when it is very big
//! and moving it from the stack is not an option, because it is bigger than the stack itself.
//! Another reason would be that you need the address of the object to initialize it. This stands
//! in direct conflict with Rust's normal process of first initializing an object and then moving
//! it into it's final memory location. For more information, see
//! <https://rust-for-linux.com/the-safe-pinned-initialization-problem>.
//!
//! This library allows you to do in-place initialization safely.
//!
//! ## Nightly Needed for `alloc` feature
//!
//! This library requires the [`allocator_api` unstable feature] when the `alloc` feature is
//! enabled and thus this feature can only be used with a nightly compiler. When enabling the
//! `alloc` feature, the user will be required to activate `allocator_api` as well.
//!
//! [`allocator_api` unstable feature]: https://doc.rust-lang.org/nightly/unstable-book/library-features/allocator-api.html
//!
//! The feature is enabled by default, thus by default `pin-init` will require a nightly compiler.
//! However, using the crate on stable compilers is possible by disabling `alloc`. In practice this
//! will require the `std` feature, because stable compilers have neither `Box` nor `Arc` in no-std
//! mode.
//!
//! ## Nightly needed for `unsafe-pinned` feature
//!
//! This feature enables the `Wrapper` implementation on the unstable `core::pin::UnsafePinned` type.
//! This requires the [`unsafe_pinned` unstable feature](https://github.com/rust-lang/rust/issues/125735)
//! and therefore a nightly compiler. Note that this feature is not enabled by default.
//!
//! # Overview
//!
//! To initialize a `struct` with an in-place constructor you will need two things:
//! - an in-place constructor,
//! - a memory location that can hold your `struct` (this can be the [stack], an [`Arc<T>`],
//!   [`Box<T>`] or any other smart pointer that supports this library).
//!
//! To get an in-place constructor there are generally three options:
//! - directly creating an in-place constructor using the [`pin_init!`] macro,
//! - a custom function/macro returning an in-place constructor provided by someone else,
//! - using the unsafe function [`pin_init_from_closure()`] to manually create an initializer.
//!
//! Aside from pinned initialization, this library also supports in-place construction without
//! pinning, the macros/types/functions are generally named like the pinned variants without the
//! `pin_` prefix.
//!
//! # Examples
//!
//! Throughout the examples we will often make use of the `CMutex` type which can be found in
//! `../examples/mutex.rs`. It is essentially a userland rebuild of the `struct mutex` type from
//! the Linux kernel. It also uses a wait list and a basic spinlock. Importantly the wait list
//! requires it to be pinned to be locked and thus is a prime candidate for using this library.
//!
//! ## Using the [`pin_init!`] macro
//!
//! If you want to use [`PinInit`], then you will have to annotate your `struct` with
//! `#[`[`pin_data`]`]`. It is a macro that uses `#[pin]` as a marker for
//! [structurally pinned fields]. After doing this, you can then create an in-place constructor via
//! [`pin_init!`]. The syntax is almost the same as normal `struct` initializers. The difference is
//! that you need to write `<-` instead of `:` for fields that you want to initialize in-place.
//!
//! ```rust
//! # #![expect(clippy::disallowed_names)]
//! # #![feature(allocator_api)]
//! # #[path = "../examples/mutex.rs"] mod mutex; use mutex::*;
//! # use core::pin::Pin;
//! use pin_init::{pin_data, pin_init, InPlaceInit};
//!
//! #[pin_data]
//! struct Foo {
//!     #[pin]
//!     a: CMutex<usize>,
//!     b: u32,
//! }
//!
//! let foo = pin_init!(Foo {
//!     a <- CMutex::new(42),
//!     b: 24,
//! });
//! # let _ = Box::pin_init(foo);

Annotation

Implementation Notes