A macro to generate self-borrowing structs, plus a few predefined type aliases for convenience.
It can sometimes occur in the course of designing an API that you find yourself in a situation where you need to store, in a single struct, both an owned value and a borrow of that value. Rust's concept of ownership and borrowing is quite flexible, but can't quite express such a scenario.
One example might be
libloading. That crate provides a
that defines methods to borrow
Symbols from it. These symbols are bounded
by the lifetime of the library, and are thus considered a borrow. Under
normal circumstances, one would be unable to store both the library and the
symbols within a single struct, but the macro defined in this crate allows
you to define a struct that is capable of storing both simultaneously.
This crate uses the term "rental" to describe this concept of a borrow that co-exsists with its owner in the same struct. The borrow itself is called the "rented" type. The "owner", naturally, is the item in the struct that owns the borrow.
The API consists of the
rental macro, which generates
rental structs, and a few premade instantiations of this macro handling
rented bare references. If you only need to rent references, see
well as the associated type aliases for common rental scenarios. The
documentation for the
rental macro describes the
kinds of items that can be generated.