#struct-of-arrays #vec #soa

nightly soa-vec

A simple Vec-like API over a struct of arrays layout

5 releases (breaking)

0.5.0 Aug 14, 2019
0.4.0 Jul 14, 2019
0.3.0 Jun 22, 2019
0.2.0 Jun 21, 2019
0.1.0 Jun 16, 2019

#1096 in Data structures

35 downloads per month

MIT license

531 lines

Soa2, Soa3, ..SoaN are generic collections with an API similar to that of a Vec of tuples but which store the data laid out as a separate slice per field. The advantage of this layout is that when iterating over the data only a subset need be loaded from RAM.

This approach is common to game engines, and entity component systems in particular but is applicable anywhere that cache coherency and memory bandwidth are important for performance.


# use soa_vec::Soa3;
/// Some 'entity' data.
# #[derive(Copy, Clone)]
struct Position { x: f64, y: f64 }
# #[derive(Copy, Clone)]
struct Velocity { dx: f64, dy: f64 }
struct ColdData { /* Potentially many fields omitted here */ }

# use std::ops::Add;
# impl Add<Velocity> for Position { type Output=Self; fn add(self, other: Velocity) -> Self { Self { x: self.x + other.dx, y: self.y + other.dy } } }
// Create a vec of entities
let mut entities = Soa3::new();
entities.push((Position {x: 1.0, y: 2.0}, Velocity { dx: 0.0, dy: 0.5 }, ColdData {}));
entities.push((Position {x: 0.0, y: 2.0}, Velocity { dx: 0.5, dy: 0.5 }, ColdData {}));

// Update entities. This loop only loads position and velocity data, while skipping over
// the ColdData which is not necessary for the physics simulation.
let (positions, velocities, _cold) = entities.iters_mut();
for (position, velocity) in positions.zip(velocities) {
	*position = *position + *velocity;

// Remove an entity

// Sort entities by position on y axis
// The fields are passed by reference, so velocity and cold data are not loaded
// until such time as the items are being swapped which runs in O(N)
# use std::cmp;
	|(lh_pos, _, _), (rh_pos, _, _)| lh_pos.y.partial_cmp(&rh_pos.y).unwrap()

// See individual structs for more methods.


This crate has strict requirements for allocations and memory layout and therefore requires the following nightly features:

  • allocator_api
  • alloc_layout_extra





If you like this, you may like these other crates by Zac Burns (That3Percent)

  • second-stack A Rust memory allocator for large slices that don't escape the stack.
  • js-intern Stores one copy of each distinct JavaScript primitive
  • js-object A macro for creating JavaScript objects