Crate temp_inst

This crate provides safe lifetime-erased representations for objects with lifetime parameters. Safety is achieved by making the lifetime-erased objects accessible only via short-lived references.

The main use case is to convert multiple (shared or mutable) references into a single reference to a lifetime-erased object, which can then be passed to an API that only accepts a single reference.

A lifetime-erased object can be obtained by creating one of TempInst, TempInstMut, or TempInstPin, and dereferencing it. (In the case of TempInstMut, the TempInstMut::call_with method should be used because TempInstMut::new is unsafe.)

To find out which types currently have a corresponding temporary representation, see the implementations of the TempRepr trait. It is possible to add temporary representations for custom types, preferably via mapped::HasTempRepr.

Examples

// We want to implement this example trait for a specific type `Bar`, in order
// to call `run_twice` below.
pub trait Foo {
    type Arg;

    fn run(arg: &mut Self::Arg);
}

pub fn run_twice<F: Foo>(arg: &mut F::Arg) {
    F::run(arg);
    F::run(arg);
}

struct Bar;

impl Foo for Bar {
    // We actually want to use _two_ mutable references as the argument type.
    // However, the associated type `Arg` does not have any lifetime parameter.
    // If we can add a lifetime parameter `'a` to `Bar`, then
    // `type Arg = (&'a mut i32, &'a mut i32)` will work. If we can't or don't
    // want to do that, a pair of `TempRefMut` will do the trick.
    type Arg = (TempRefMut<i32>, TempRefMut<i32>);

    fn run(arg: &mut Self::Arg) {
        // The mutable `TempRefMut` references can be dereferenced to obtain
        // the mutable references that we passed to `call_with` below.
        let (a_ref, b_ref) = arg;
        **a_ref += **b_ref;
        **b_ref += 1;
    }
}

let mut a = 42;
let mut b = 23;

// Now we can convert the pair `(&mut a, &mut b)` to `&mut Foo::Arg`, and pass
// that to `run_twice`.
TempInstMut::call_with((&mut a, &mut b), run_twice::<Bar>);

assert_eq!(a, 42 + 23 + 1 + 23);
assert_eq!(b, 23 + 1 + 1);

For shared or pinned mutable references, there is a slightly simpler API:

pub trait Foo {
    type Arg;

    fn run(arg: &Self::Arg) -> i32;
}

fn run_twice_and_add<F: Foo>(arg: &F::Arg) -> i32 {
    F::run(arg) + F::run(arg)
}

struct Bar;

impl Foo for Bar {
    type Arg = (TempRef<i32>, TempRef<i32>);

    fn run(arg: &Self::Arg) -> i32 {
        let (a_ref, b_ref) = arg;
        **a_ref * **b_ref
    }
}

let inst = TempInst::new((&42, &23));
let sum_of_products = run_twice_and_add::<Bar>(&inst);

assert_eq!(sum_of_products, 42 * 23 + 42 * 23);

For another use case, see the temp_stack crate.

Modules

mapped

Contains a trait HasTempRepr to implement TempRepr and TempReprMut by mapping to and from built-in types.

Structs

SelfRepr

A wrapper type that trivially implements TempRepr/TempReprMut for any T: Clone in such a way that no lifetimes are erased.

TempInst

A wrapper around an instance of T which implements TempRepr, i.e. is a temporary representation of a type T::Shared<'a>.

TempInstMut

A wrapper around an instance of T which implements TempReprMut, i.e. is a temporary representation of a type T::Mutable<'a>.

TempInstPin

A wrapper around an instance of T which implements TempReprMut, i.e. is a temporary representation of a type T::Mutable<'a>.

TempRef

The canonical implementation of TempRepr, representing a single shared reference.

TempRefMut

The canonical implementation of TempReprMut, representing a single mutable reference.

TempRefPin

Similar to TempRefMut, but represents a pinned mutable reference.

Enums

TempCow

A temporary representation of alloc::borrow::Cow.

Traits

AlwaysShared

A marker trait that causes TempReprMut to be implemented identically to TempRepr.

TempRepr

A trait that specifies that a type is a “temporary representation” of another type, where that other type can depend on a lifetime (via GATs). The standard example is that a raw pointer can be regarded as a temporary representation of a reference. The trait implementation for tuples generalizes this to combinations of more than one pointer/reference, the trait implementation for Option extends it to optional references, etc.

TempReprMut

An extension of TempRepr that adds support for mutable references.

TempReprMutChk

An extension of TempReprMut that allows non-pinned mutable references to be passed to safe client code.

Functions

set_modification_panic_fn^⚠

Sets an alternative function to be called by the Drop implementation of TempInstMut when it encounters an illegal modification.

Type Aliases

TempChars

TempSliceIter

TempSliceIterMut