Crate rental [] [src]

A macro to generate self-borrowing structs, plus a few predefined type aliases for convenience.

Overview

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 Library struct 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 RentRef and RentMut, as 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.

Macros

rental

This macro is the bedrock of the API. It allows you to define three different kinds of items related to renting.

Structs

MapMut

A mapper that can convert one rental into another, provided they have identical owner types.

MapRef

A mapper that can convert one rental into another, provided they have identical owner types.

RentMut

A struct representing a particular mutable (owner, rental) pair.

RentRef

A struct representing a particular (owner, rental) pair.

Traits

FixedDeref

This trait indicates both that the type can be dereferenced, and that when it is, the target has a fixed memory address while it is held by a rental struct.

Rental

This trait is implemented for all generated rental structs.

RentalMut

This trait is implemented for all mutable rental structs.

Type Definitions

RentArc

A predefined type that rents values from an Arc<T>.

RentBox

A predefined type that rents values from a Box<T>.

RentBoxMut

A predefined type that rents mutable values from a Box<T>.

RentMutex

A predefined type that rents values from a MutexGuard<T>.

RentMutexMut

A predefined type that rents mutable values from a MutexGuard<T>.

RentRefCell

A predefined type that rents values from a Ref<T>.

RentRefCellMut

A predefined type that rents mutable values from a RefMut<T>.

RentRwLock

A predefined type that rents values from an RwLockReadGuard<T>.

RentRwLockMut

A predefined type that rents mutable values from an RwLockWriteGuard<T>.

RentString

A predefined type that rents values from a String.

RentStringMut

A predefined type that rents mutable values from a String.

RentVec

A predefined type that rents values from a Vec<T>.

RentVecMut

A predefined type that rents mutable values from a Vec<T>.