# Data layout, SIMD and threads

> soa and aos as part of the type, vector values against arrays in memory, vec loops that must vectorize, and par.

This page is about the part of the language that the rest exists to carry: layout, vectors and threads.

## Layout is a property of the array type

Layout is a qualifier on an array or slice type. `soa []Body` stores one array per field; `aos []Body` stores records back to back. The same `rec` works with either, and field access is written the same way, so changing the layout is changing a type, not rewriting the code.

```lane
rec Body { f32 x; f32 vx; }

nul step(wr soa []Body b, f32 dt) {
    par vec i in 0..b.len {
        b.x[i] += b.vx[i] * dt;
    }
}
```

An `aos` slice is indexed as records:

```lane
usz count_heavy(aos []Body b, f32 limit) {
    n := 0;
    for i in 0..b.len {
        if b[i].mass <= limit { nxt; }
        n += 1;
        if n == N { brk; }
    }
    ret n;
}
```

A benchmark can build an `soa` array in place, which a test or `bench` block may use:

```lane
bench "step 1M bodies" {
    soa [1_000_000]Body b;
    step(wr b, 1.0e-3);
}
```

## Vectors: a register value is not an array

Vectors are written `<scalar>x<lanes>`. `f32x4` is one SIMD register holding four floats and is a value. `[4]f32` is four floats in memory. They are different types, and the language does not let one stand in for the other. `f32xw` has as many lanes as the target's widest vector: 16 with AVX-512, 8 with AVX2, 4 with NEON or SIMD128.

```lane
f32xw splat_scale(f32xw v, f32 s) {
    ret v * f32xw(s);
}
```

A kernel is written once against these width-generic types and lowered per target. Raw instructions are still available: functions in per-architecture modules (`x86.*`, `arm.*`), legal only in a branch that selects that architecture (see [Per-ISA code, hints and floats](/docs/targets-hints.md)), and `asm { }` blocks.

## vec: vectorize or fail

`vec i in a..b { }` must vectorize at the target's native width. If it cannot, that is a compile error, never a silent scalar loop.

```lane
nul axpy(wr []f32 y, []f32 x, f32 a) {
    vec i in 0..y.len {
        y[i] += a * x[i];
    }
}
```

A `vec` loop that accumulates floats needs `reassoc` (see [floating point](/docs/targets-hints.md#floating-point)); without it the loop is a compile error, never silently reordered. An indirect call inside a `vec` loop is a compile error.

A vectorized kernel can name its scalar reference with `@ref`, and is then differential-tested against it on generated inputs:

```lane
usz count_range_ref([]i32 col, i32 lo, i32 hi) {
    usz n = 0;
    for i in 0..col.len {
        if col[i] >= lo && col[i] < hi { n += 1; }
    }
    ret n;
}
```

```lane
@ref(count_range_ref)
usz count_range([]i32 col, i32 lo, i32 hi) {
```

## par: threads as a keyword

`par` runs a loop or block across cores and joins at the end. The `wr` sets of the pieces must not overlap. That condition is checkable because parameters carry access modes, and a call repeats the mode of each argument (see [Declarations and functions](/docs/declarations.md)).

How `par` schedules work, the job system and its C ABI, is still an open question in the specification.

## Shaders

Lane is meant to compile a subset to SPIR-V later, so one language covers CPU kernels and GPU shaders, with shared records and math and with shader functions testable on the CPU. To keep that possible, the pure subset (no pointers, no function pointers, no `asm`, no `par`, no recursion) must stay a well-defined part of the language, record layout rules must be able to match GPU buffer layouts, and `vec` loops over `soa` data should be expressible as compute shaders. This is a design constraint, not a feature.
