VecStorage

Re-use the memory for vectors containing values with different lifetimes

In some situations, e.g. when writing real-time audio software, memory needs to be pre-allocated. The Vec data structure from Rust's standard library can be used for this purpose. In some situations, however, you want to re-use the same Vec for data that has different lifetimes and Rust's type system doesn't allow this. This crate intends to help you overcome this problem.

Example

The following code does not compile:

let mut v = Vec::with_capacity(2);
{
    let x = 1; let y = 2;
    v.push(&x);
    v.push(&y);
    v.clear(); // We stop borrowing here, but the compiler doesn't know that.
}
{
    let a = 1; let b = 2;
    v.push(&a);
    v.push(&b);
    v.clear(); // We stop borrowing here, but the compiler doesn't know that.
}

You can use VecStorage to solve this problem:

use vecstorage::VecStorage;
let mut v = VecStorage::<&u32>::with_capacity(2);
{
    let x = 1; let y = 2;
    let mut guard = v.vec_guard();
    // Now guard behaves like a vector.
    guard.push(&x); // No memory allocation here, we use the memory allocated in `v`.
    guard.push(&y);
    // If we were going to push more items on the guard, we would allocate memory.
    // When guard goes out of scope, it is cleared.
}
{
    let a = 1; let b = 2;
    let mut guard = v.vec_guard();
    // Now guard behaves like a vector.
    // The memory from the previous run has been cleared ...
    assert_eq!(guard.len(), 0);
    guard.push(&a);
    guard.push(&b);
}

Documentation

See the documentation on docs.rs.

Related Crates

rsor (short for "Reusable Slice Of References") is developed to re-use the memory for containing references and can be used as an alternative to vecstorage if you want to store references. rsor has a different API that does not rely on run-time checks (in contrast to vecstorage which does some runtime checks).

Contributing

We welcome contributions, both in the form of issues and in the form of pull requests. Before opening a pull request, please open an issue first so that you know whether a subsequent pull request would likely be approved. Alternatively, you can contribute via e-mail (an email address is in the commits).

It's best to run the automated tests before sending your contribution.

Testing

Since this crate uses some unsafe blocks, we run the tests both "in a normal way" and under miri.

Running the tests normally:

cargo test

In order to run the tests under miri, you need to have the miri component installed. Then you can run the tests under miri as follows:

cargo +nightly miri test -- --skip forgetting
export MIRIFLAGS=-Zmiri-ignore-leaks
cargo +nightly miri test forgetting

License

Vecstorage is distributed under the terms of the MIT license or the Apache License (Version 2.0), at your choice. For the application of the MIT license, the examples included in the doc comments are not considered "substatial portions of this Software".