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