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## Examples
22
23[`pin_project!`] macro creates a projection type covering all the fields of
24struct.
25
26```rust
27use std::pin::Pin;
28
29use pin_project_lite::pin_project;
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 std::pin::Pin;
53
54use pin_project_lite::pin_project;
55
56pin_project! {
57 #[project = EnumProj]
58 enum Enum<T, U> {
59 Variant { #[pin] pinned: T, unpinned: U },
60 }
61}
62
63impl<T, U> Enum<T, U> {
64 fn method(self: Pin<&mut Self>) {
65 match self.project() {
66 EnumProj::Variant { pinned, unpinned } => {
67 let _: Pin<&mut T> = pinned;
68 let _: &mut U = unpinned;
69 }
70 }
71 }
72}
73```
74
75## [pin-project] vs pin-project-lite
76
77Here are some similarities and differences compared to [pin-project].
78
79### Similar: Safety
80
81pin-project-lite guarantees safety in much the same way as [pin-project].
82Both are completely safe unless you write other unsafe code.
83
84### Different: Minimal design
85
86This library does not tackle as expansive of a range of use cases as
87[pin-project] does. If your use case is not already covered, please use
88[pin-project].
89
90### Different: No proc-macro related dependencies
91
92This is the **only** reason to use this crate. However, **if you already
93have proc-macro related dependencies in your crate's dependency graph, there
94is no benefit from using this crate.** (Note: There is almost no difference
95in the amount of code generated between [pin-project] and pin-project-lite.)
96
97### Different: No useful error messages
98
99This macro does not handle any invalid input. So error messages are not to
100be useful in most cases. If you do need useful error messages, then upon
101error you can pass the same input to [pin-project] to receive a helpful
102description of the compile error.
103
104### Different: No support for custom Unpin implementation
105
106pin-project supports this by [`UnsafeUnpin`][unsafe-unpin]. (`!Unpin` is supported by both [pin-project][not-unpin] and [pin-project-lite][not-unpin-lite].)
107
108### Different: No support for tuple structs and tuple variants
109
110pin-project supports this.
111
112[not-unpin]: https://docs.rs/pin-project/latest/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/latest/pin_project/attr.pin_project.html#unsafeunpin
115
116<!-- tidy:crate-doc:end -->
117
118[not-unpin-lite]: https://docs.rs/pin-project-lite/latest/pin_project_lite/macro.pin_project.html#unpin
119[`pin_project!`]: https://docs.rs/pin-project-lite/latest/pin_project_lite/macro.pin_project.html
120
121## License
122
123Licensed under either of [Apache License, Version 2.0](LICENSE-APACHE) or
124[MIT license](LICENSE-MIT) at your option.
125
126Unless you explicitly state otherwise, any contribution intentionally submitted
127for inclusion in the work by you, as defined in the Apache-2.0 license, shall
128be dual licensed as above, without any additional terms or conditions.
129