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