Array of Struct to Struct of Array helpers in Rust
Branch: master
Clone or download
Latest commit 109a728 Dec 11, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
benches Update benchmarks Dec 11, 2018
example Check all rustc and clippy lints in the example Sep 9, 2018
soa-derive-internal Parametrize clippy Dec 11, 2018
src Update soa-derive to use edition 2018 Dec 11, 2018
tests Update soa-derive to use edition 2018 Dec 11, 2018
.gitignore Initial commit for soa using custom derive Mar 10, 2017
.travis.yml Update documentation for the new soa_zip macro Dec 21, 2017
Cargo.toml Update soa-derive to use edition 2018 Dec 11, 2018
LICENSE-APACHE Add MIT/Apache licence Jul 11, 2017
LICENSE-MIT Add MIT/Apache licence Jul 11, 2017
README.md

README.md

Automatic Struct of Array generation for Rust

Build Status Crates.io

This crate provides a custom derive (#[derive(StructOfArray)]) to automatically generate code from a given struct T that allow to replace Vec<T> with a struct of arrays. For example, the following code

#[derive(StructOfArray)]
pub struct Cheese {
    pub smell: f64,
    pub color: (f64, f64, f64),
    pub with_mushrooms: bool,
    pub name: String,
}

will generate a CheeseVec struct that looks like this:

pub struct CheeseVec {
    pub smell: Vec<f64>,
    pub color: Vec<(f64, f64, f64)>,
    pub with_mushrooms: Vec<bool>,
    pub name: Vec<String>,
}

It will also generate the same functions that a Vec<Chees> would have, and a few helper structs: CheeseSlice, CheeseSliceMut, CheeseRef and CheeseRefMut corresponding respectivly to &[Cheese], &mut [Cheese], &Cheese and &mut Cheese.

How to use it

Add #[derive(StructOfArray)] to each struct you want to derive a struct of array version. If you need the helper structs to derive additional traits (such as Debug or PartialEq), you can add an attribute #[soa_derive = "Debug, PartialEq"] to the struct declaration.

#[derive(Debug, PartialEq, StructOfArray)]
#[soa_derive = "Debug, PartialEq"]
pub struct Cheese {
    pub smell: f64,
    pub color: (f64, f64, f64),
    pub with_mushrooms: bool,
    pub name: String,
}

Usage and API

All the generated code have some generated documentation with it, so you should be able to use cargo doc on your crate and see the documentation for all the generated structs and functions. Most of the time, you should be able to replace Vec<Cheese> by CheeseVec, with exception of code using direct indexing in the vector and a few other caveats listed below.

Caveats and limitations

Vec<T> functionalities rely a lot on references and automatic deref feature, for getting function from [T] and indexing. But the SoA vector (let's call it CheeseVec, generated from the Cheese struct) generated by this crate can not implement Deref<Target=CheeseSlice>, because Deref is required to return a reference, and CheeseSlice is not a reference. The same applies to Index and IndexMut trait, that can not return CheeseRef/CheeseRefMut. This means that the we can not index into a CheeseVec, and that a few functions are duplicated, or require a call to as_ref()/as_mut() to change the type used.

Iteration

It is possible to iterate over the values in a CheeseVec

let mut vec = CheeseVec::new();
vec.push(Cheese::new("stilton"));
vec.push(Cheese::new("brie"));

for cheese in vec.iter() {
    // when iterating over a CheeseVec, we load all members from memory
    // in a CheeseRef
    let typeof_cheese: CheeseRef = cheese;
    println!("this is {}, with a smell power of {}", cheese.name, cheese.smell);
}

One of the main advantage of the SoA layout is to be able to only load some fields from memory when iterating over the vector. In order to do so, one can manually pick the needed fields:

for name in &vec.name {
    // We get referenes to the names
    let typeof_name: &String = name;
    println!("got cheese {}", name);
}

In order to iterate over multiple fields at the same time, one can use the soa_zip! macro.

for (name, smell, color) in soa_zip!(vec, [name, mut smell, color]) {
    println!("this is {}, with color {:#?}", name, color);
    // smell is a mutable reference
    *smell += 1.0;
}

Documentation

Please see http://lumol.org/soa-derive/soa_derive_example/ for a small example and the documentation of all the generated code.

Benchmarks

Here are a few simple benchmarks results, on my machine:

running 10 tests
test aos_big_do_work_1000    ... bench:         997 ns/iter (+/- 192)
test aos_big_do_work_10000   ... bench:      21,324 ns/iter (+/- 3,282)
test aos_big_push            ... bench:          93 ns/iter (+/- 17)
test aos_small_do_work_10000 ... bench:       8,822 ns/iter (+/- 1,459)
test aos_small_push          ... bench:          10 ns/iter (+/- 4)
test soa_big_do_work_1000    ... bench:         890 ns/iter (+/- 142)
test soa_big_do_work_10000   ... bench:      10,538 ns/iter (+/- 1,621)
test soa_big_push            ... bench:         171 ns/iter (+/- 44)
test soa_small_do_work_10000 ... bench:       8,978 ns/iter (+/- 1,538)
test soa_small_push          ... bench:          24 ns/iter (+/- 6)

Benchmarks tests exist for soa (struct of array) and aos (array of struct) versions of the same code, using a small and a big struct.

You can run the same benchmarks on your own system by cloning this repository and running cargo bench.

Licensing and contributions

This crate distributed under either the MIT or the Apache license, at your choice. Contributions are welcome, please open an issue before to discuss your changes !

The code is based on an initial idea by @maikklein: https://maikklein.github.io/post/soa-rust/