README.md
1# pin-project-lite
2
3[](https://crates.io/crates/pin-project-lite)
4[](https://docs.rs/pin-project-lite)
5[](#license)
6[](https://www.rust-lang.org)
7[](https://github.com/taiki-e/pin-project-lite/actions)
8
9A lightweight version of [pin-project] written with declarative macros.
10
11## Usage
12
13Add this to your `Cargo.toml`:
14
15```toml
16[dependencies]
17pin-project-lite = "0.2"
18```
19
20*Compiler support: requires rustc 1.37+*
21
22## Examples
23
24[`pin_project!`] macro creates a projection type covering all the fields of
25struct.
26
27```rust
28use pin_project_lite::pin_project;
29use std::pin::Pin;
30
31pin_project! {
32 struct Struct<T, U> {
33 #[pin]
34 pinned: T,
35 unpinned: U,
36 }
37}
38
39impl<T, U> Struct<T, U> {
40 fn method(self: Pin<&mut Self>) {
41 let this = self.project();
42 let _: Pin<&mut T> = this.pinned; // Pinned reference to the field
43 let _: &mut U = this.unpinned; // Normal reference to the field
44 }
45}
46```
47
48To use [`pin_project!`] on enums, you need to name the projection type
49returned from the method.
50
51```rust
52use pin_project_lite::pin_project;
53use std::pin::Pin;
54
55pin_project! {
56 #[project = EnumProj]
57 enum Enum<T, U> {
58 Variant { #[pin] pinned: T, unpinned: U },
59 }
60}
61
62impl<T, U> Enum<T, U> {
63 fn method(self: Pin<&mut Self>) {
64 match self.project() {
65 EnumProj::Variant { pinned, unpinned } => {
66 let _: Pin<&mut T> = pinned;
67 let _: &mut U = unpinned;
68 }
69 }
70 }
71}
72```
73
74## [pin-project] vs pin-project-lite
75
76Here are some similarities and differences compared to [pin-project].
77
78### Similar: Safety
79
80pin-project-lite guarantees safety in much the same way as [pin-project].
81Both are completely safe unless you write other unsafe code.
82
83### Different: Minimal design
84
85This library does not tackle as expansive of a range of use cases as
86[pin-project] does. If your use case is not already covered, please use
87[pin-project].
88
89### Different: No proc-macro related dependencies
90
91This is the **only** reason to use this crate. However, **if you already
92have proc-macro related dependencies in your crate's dependency graph, there
93is no benefit from using this crate.** (Note: There is almost no difference
94in the amount of code generated between [pin-project] and pin-project-lite.)
95
96### Different: No useful error messages
97
98This macro does not handle any invalid input. So error messages are not to
99be useful in most cases. If you do need useful error messages, then upon
100error you can pass the same input to [pin-project] to receive a helpful
101description of the compile error.
102
103### Different: No support for custom Unpin implementation
104
105pin-project supports this by [`UnsafeUnpin`][unsafe-unpin] and [`!Unpin`][not-unpin].
106
107### Different: No support for tuple structs and tuple variants
108
109pin-project supports this.
110
111[`pin_project!`]: https://docs.rs/pin-project-lite/0.2/pin_project_lite/macro.pin_project.html
112[not-unpin]: https://docs.rs/pin-project/1/pin_project/attr.pin_project.html#unpin
113[pin-project]: https://github.com/taiki-e/pin-project
114[unsafe-unpin]: https://docs.rs/pin-project/1/pin_project/attr.pin_project.html#unsafeunpin
115
116## License
117
118Licensed under either of [Apache License, Version 2.0](LICENSE-APACHE) or
119[MIT license](LICENSE-MIT) at your option.
120
121Unless you explicitly state otherwise, any contribution intentionally submitted
122for inclusion in the work by you, as defined in the Apache-2.0 license, shall
123be dual licensed as above, without any additional terms or conditions.
124