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