Macro rental::rental

macro_rules! rental {
    {
		$(#[$attr:meta])*
		mod $rental_mod:ident {
			$($body:tt)*
		}
	} => { ... };
    {
		$(#[$attr:meta])*
		pub mod $rental_mod:ident {
			$($body:tt)*
		}
	} => { ... };
    {
		$(#[$attr:meta])*
		pub($($vis:tt)*) mod $rental_mod:ident {
			$($body:tt)*
		}
	} => { ... };
}

The bedrock of this crate, this macro will generate self-referential structs.

This macro is invoked in item position. The body parses as valid rust and contains no special syntax. Only certain constructs are allowed, and a few special attributes and lifetimes are recognized.

To start, the top level item of the macro invocation must be a single module. This module will contain all items that the macro generates and export them to you. Within the module, only three types of items are accepted: use statements, type aliases, and struct definitions. The use statements and type aliases are passed directly through with no special consideration; the primary concern is the struct definitions.

First, all struct definitions must have a #[rental] or #[rental_mut] attribute to indicate that they are self-referential. The mut variant indicates that the struct mutably borrows itself, while the normal attribute assumes shared borrows. These attributes also accept certain flags to enable specific features, described below.

Next, the structs must have named fields (no tuple structs) and they must have at least 2 fields, since a struct with 1 field can't meaningfully reference itself anyway.

The order of the fields is significant, as they are declared in order of least to most dependent. The first field, also referred to as the "head" of the struct, contains no self-references, the second field may borrow the first, the third field may borrow the second or first, and so on. The chain of fields after the head is called the "tail".

Because rental structs are self-referential, special care is taken to ensure that moving the struct will not invalidate any internal references. This is accomplished by requiring all fields but the last one, collectively known as the "prefix" of the struct, to implement StableDeref. This is not required for the final field of the struct, known as the "suffix", since nothing holds a reference to it.

NOTE: Because of a workaround for a compiler bug, rental might not always correctly determine the Deref::Target type of your prefix fields. If you receive type errors when compiling, you can try using the target_ty attribute on the field of the struct. Set this attribute equal to a string that names the correct target type (e.g. #[target_ty = "[u8]"] for Vec<u8>.

Each field that you declare creates a special lifetime of the same name that can be used by later fields to borrow it. This is how the referential relationships are established in the struct definition.

This is a all a bit to chew on so far, so let's stop and take a look at an example:

pub struct Foo { i: i32 }
pub struct Bar<'a> { foo: &'a Foo }
pub struct Qux<'a: 'b, 'b> { bar: &'b Bar<'a> }
 
rental! {
    mod my_rentals {
        use super::*;

        #[rental]
        pub struct MyRental {
            foo: Box<Foo>,
            bar: Box<Bar<'foo>>,
            qux: Qux<'foo, 'bar>,
        }
    }
}

Here we see each field use the special lifetimes of the previous fields to establish the borrowing chain.

In addition to the rental struct itself, two other structs are generated, with _Borrow and _BorrowMut appended to the original struct name (e.g. MyRental_Borrow and MyRental_BorrowMut). These structs contain the same fields as the original struct, but are borrows of the originals. These structs are passed into certain closures that you provide to the rent_all suite of methods to allow you access to the struct's fields. For mutable rentals, these structs will only contain a borrow of the suffix; the other fields will be erased with PhantomData.

Attribute Flags

A rental or rental_mut attribute accepts various options that affect the code generated by the macro to add certain features if your type supports them. These flags are placed in parens after the attribute, similar to the cfg attribute, e.g. #[rental(debug)].

debug

If all the fields of your struct implement Debug then you can use the debug option on the rental attribute to gain a Debug impl on the struct itself. For mutable rental structs, only the suffix field needs to be Debug, as it is the only one that will be printed. The prefix fields are mutably borrowed so cannot be accessed while the suffix exists.

clone

If the prefix fields of your struct impl CloneStableDeref (which means clones still deref to the same object), and the suffix field is Clone, then your rental struct can be Clone as well.

deref_suffix / deref_mut_suffix

If the suffix field of the struct implements Deref or DerefMut, you can add a deref_suffix or deref_mut_suffix argument to the rental attribute on the struct. This will generate a Deref implementation for the rental struct itself that will deref through the suffix and return the borrow to you, for convenience. Note, however, that this will only be legal if none of the special rental lifetimes appear in the type signature of the deref target. If they do, exposing them to the outside world could result in unsafety, so this is not allowed and such a scenario will not compile.

covariant

Since the true lifetime of a self-referential field is currently inexpressible in rust, the lifetimes the fields use internally are fake. This means that directly borrowing the fields of the struct would be quite unsafe. However, if we know that the type is covariant over its lifetime parameters, then we can reborrow away the fake rental lifetimes to something concrete and safe. This tag will provide methods that access the fields of the struct directly, while also ensuring that the covariance requirement is met, otherwise the struct will fail to compile. For an exmaple see SimpleRefCovariant.

map_suffix = "T"

For rental structs that contain some kind of smart reference as their suffix field, such as a Ref or MutexGuard, it can be useful to be able to map the reference to another type. This option allows you to do so, given certain conditions. First, your rental struct must have a type parameter in the position that you want to map, such as Ref<'head, T> or MutexGuard<'head, T>. Second, this type param must ONLY be used in the suffix field. Specify the type parameter you wish to use with map_suffix = "T" where T is the name of the type param that satisfies these conditions. For an example of the methods this option provides, see SimpleRefMap.

Subrentals

Finally, there is one other capability to discuss. If a rental struct has been defined elsewhere, either in our own crate or in a dependency, we'd like to be able to chain our own rental struct off of it. In this way, we can use another rental struct as a sort of pre-packaged prefix of our own. As a variation on the above example, it would look like this:

pub struct Foo { i: i32 }
pub struct Bar<'a> { foo: &'a Foo }
pub struct Qux<'a: 'b, 'b> { bar: &'b Bar<'a> }
 
rental! {
    mod my_rentals {
        use super::*;

        #[rental]
        pub struct OtherRental {
            foo: Box<Foo>,
            bar: Bar<'foo>,
        }
         
        #[rental]
        pub struct MyRental {
            #[subrental = 2]
            prefix: Box<OtherRental>,
            qux: Qux<'prefix_0, 'prefix_1>,
        }
    }
}

The first rental struct is fairly standard, so we'll focus on the second one. The head field is given a subrental attribute and set equal to an integer indicating the arity. The arity of a rental struct is the number of special lifetimes it creates. As can be seen above, the first struct has two fields, neither of which is itself a subrental, so it has an arity of 2. The arity of the second struct would be 3, since it includes the two fields of the first rental as well as one new one. In this way, arity is transitive. So if we used our new struct itself as a subrental of yet another struct, we'd need to declare the field with subrental = 3. The special lifetimes created by a subrental are the field name followed by a _ and a zero-based index. Also note that the suffix field cannot itself be a subrental, only prefix fields.

This covers the essential capabilities of the macro itself. For details on the API of the structs themselves, see the examples module.