• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# pin-project
2
3[![crates.io](https://img.shields.io/crates/v/pin-project?style=flat-square&logo=rust)](https://crates.io/crates/pin-project)
4[![docs.rs](https://img.shields.io/badge/docs.rs-pin--project-blue?style=flat-square&logo=docs.rs)](https://docs.rs/pin-project)
5[![license](https://img.shields.io/badge/license-Apache--2.0_OR_MIT-blue?style=flat-square)](#license)
6[![msrv](https://img.shields.io/badge/msrv-1.56-blue?style=flat-square&logo=rust)](https://www.rust-lang.org)
7[![github actions](https://img.shields.io/github/actions/workflow/status/taiki-e/pin-project/ci.yml?branch=main&style=flat-square&logo=github)](https://github.com/taiki-e/pin-project/actions)
8
9<!-- tidy:crate-doc:start -->
10A crate for safe and ergonomic [pin-projection].
11
12## Usage
13
14Add this to your `Cargo.toml`:
15
16```toml
17[dependencies]
18pin-project = "1"
19```
20
21## Examples
22
23[`#[pin_project]`][`pin_project`] attribute creates projection types
24covering all the fields of struct or enum.
25
26```rust
27use std::pin::Pin;
28
29use pin_project::pin_project;
30
31#[pin_project]
32struct Struct<T, U> {
33    #[pin]
34    pinned: T,
35    unpinned: U,
36}
37
38impl<T, U> Struct<T, U> {
39    fn method(self: Pin<&mut Self>) {
40        let this = self.project();
41        let _: Pin<&mut T> = this.pinned; // Pinned reference to the field
42        let _: &mut U = this.unpinned; // Normal reference to the field
43    }
44}
45```
46
47[*code like this will be generated*][struct-default-expanded]
48
49To use `#[pin_project]` on enums, you need to name the projection type
50returned from the method.
51
52```rust
53use std::pin::Pin;
54
55use pin_project::pin_project;
56
57#[pin_project(project = EnumProj)]
58enum Enum<T, U> {
59    Pinned(#[pin] T),
60    Unpinned(U),
61}
62
63impl<T, U> Enum<T, U> {
64    fn method(self: Pin<&mut Self>) {
65        match self.project() {
66            EnumProj::Pinned(x) => {
67                let _: Pin<&mut T> = x;
68            }
69            EnumProj::Unpinned(y) => {
70                let _: &mut U = y;
71            }
72        }
73    }
74}
75```
76
77[*code like this will be generated*][enum-default-expanded]
78
79See [`#[pin_project]`][`pin_project`] attribute for more details, and
80see [examples] directory for more examples and generated code.
81
82## Related Projects
83
84- [pin-project-lite]: A lightweight version of pin-project written with declarative macros.
85
86[enum-default-expanded]: https://github.com/taiki-e/pin-project/blob/HEAD/examples/enum-default-expanded.rs
87[examples]: https://github.com/taiki-e/pin-project/blob/HEAD/examples/README.md
88[pin-project-lite]: https://github.com/taiki-e/pin-project-lite
89[pin-projection]: https://doc.rust-lang.org/std/pin/index.html#projections-and-structural-pinning
90[struct-default-expanded]: https://github.com/taiki-e/pin-project/blob/HEAD/examples/struct-default-expanded.rs
91
92<!-- tidy:crate-doc:end -->
93
94[`pin_project`]: https://docs.rs/pin-project/latest/pin_project/attr.pin_project.html
95
96## License
97
98Licensed under either of [Apache License, Version 2.0](LICENSE-APACHE) or
99[MIT license](LICENSE-MIT) at your option.
100
101Unless you explicitly state otherwise, any contribution intentionally submitted
102for inclusion in the work by you, as defined in the Apache-2.0 license, shall
103be dual licensed as above, without any additional terms or conditions.
104