Nicholas Nethercote
d1e364e6d5
By removal internal rules, this commit turns one giant macro with 47
rules into 23 macros with a small number of rules each. I find the
resulting code *much* easier to read; I found the original giant macro
quite overwhelming. The new code also needs fewer comments because the
code is clearer.
The commit also fixes some minor formatting inconsistencies, such as
always putting a space between the `!` and the `{` in a macro
invocation, and using parens instead of braces for a few matchers.
pin-project-lite
A lightweight version of pin-project written with declarative macros.
Usage
Add this to your Cargo.toml:
[dependencies]
pin-project-lite = "0.2"
Compiler support: requires rustc 1.37+
Examples
pin_project! macro creates a projection type covering all the fields of
struct.
use std::pin::Pin;
use pin_project_lite::pin_project;
pin_project! {
struct Struct<T, U> {
#[pin]
pinned: T,
unpinned: U,
}
}
impl<T, U> Struct<T, U> {
fn method(self: Pin<&mut Self>) {
let this = self.project();
let _: Pin<&mut T> = this.pinned; // Pinned reference to the field
let _: &mut U = this.unpinned; // Normal reference to the field
}
}
To use pin_project! on enums, you need to name the projection type
returned from the method.
use std::pin::Pin;
use pin_project_lite::pin_project;
pin_project! {
#[project = EnumProj]
enum Enum<T, U> {
Variant { #[pin] pinned: T, unpinned: U },
}
}
impl<T, U> Enum<T, U> {
fn method(self: Pin<&mut Self>) {
match self.project() {
EnumProj::Variant { pinned, unpinned } => {
let _: Pin<&mut T> = pinned;
let _: &mut U = unpinned;
}
}
}
}
pin-project vs pin-project-lite
Here are some similarities and differences compared to pin-project.
Similar: Safety
pin-project-lite guarantees safety in much the same way as pin-project. Both are completely safe unless you write other unsafe code.
Different: Minimal design
This library does not tackle as expansive of a range of use cases as pin-project does. If your use case is not already covered, please use pin-project.
Different: No proc-macro related dependencies
This is the only reason to use this crate. However, if you already have proc-macro related dependencies in your crate's dependency graph, there is no benefit from using this crate. (Note: There is almost no difference in the amount of code generated between pin-project and pin-project-lite.)
Different: No useful error messages
This macro does not handle any invalid input. So error messages are not to be useful in most cases. If you do need useful error messages, then upon error you can pass the same input to pin-project to receive a helpful description of the compile error.
Different: No support for custom Unpin implementation
pin-project supports this by UnsafeUnpin and !Unpin.
Different: No support for tuple structs and tuple variants
pin-project supports this.
License
Licensed under either of Apache License, Version 2.0 or MIT license at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.