`nupp.mem.soa`

Structure-of-arrays storage for reified structs.

Every top-level field of a reified struct gets its own contiguous column, so a loop that walks one field of many rows brings nothing else along.

local soa = nupp.mem.soa

local struct Position
    x: float
    velocity: float
end

local positions = soa.allocate(ffi.typeof<Position>(), 128)
with rows = positions:write() do
    for index = 1, #rows do
        rows[index].x += rows[index].velocity
    end
end

The compiler supplies the private layout argument to allocate and layoutof, and lowers indexed row fields directly to the typed columns kept by these views. This module owns allocation, checked whole-row operations, slicing, and field-span construction; it never exposes the slab or its column pointers in the public types.

See Structure-of-arrays storage for when this layout is the one to reach for, and NEP 10: Structure-of-arrays storage for why the container rather than the declaration chooses it.

Module contents

Types

Type	Kind	Description
`Array`	record	One owned native slab whose top-level struct fields occupy separate segments.
`ArrayToken`	interface
`FieldLayout`	record	One stored top-level field in a SoA descriptor.
`InstanceLayout`	record	The count-dependent layout of one complete SoA slab.
`Layout`	record	Immutable reflection for a reified struct's SoA representation.
`SegmentLayout`	record	One field segment for a particular element count.
`Span`	interface	A shared checked view over SoA rows.
`Writable`	type	An affine exclusive row view, released at its lexical boundary.
`WriteSpan`	interface	An affine exclusive checked view over SoA rows.
`WriteToken`	interface

Functions

Function	Kind	Description
`allocate`	function	Allocates one SoA slab for a reified struct type.
`destroyArray`	function	Frees a slab, which is what every SoA array's contract names.
`destroyWriteSpan`	function	Ends a row writer, which is what every writable row view's contract names.
`layoutof`	function	Answers immutable SoA reflection for a reified struct type without allocating.

Types#

`Array`record#

record soa.Array<T> is soa.ArrayToken
    readonly count: integer
    readonly fingerprint: string
    read: function(borrows self: Array<T>): soa.Span<T> borrows (self)
    write: function(
        exclusive self: Array<T>
    ): affine(soa.WriteToken & soa.WriteSpan<T>, soa.destroyWriteSpan) borrows (self)
    close: nosuspend function(takes self: Array<T>): nil

    drop: nosuspend function(takes self: Array<T>): nil
end

One owned native slab whose top-level struct fields occupy separate segments.

Type parameters

Name	Description
`T`

Methods

`read`#

read: function(borrows self: Array<T>): soa.Span<T> borrows (self)

Borrows the rows as a shared checked view.

The borrow lasts as long as the view does, so a writer cannot be taken out while one is live.

Arguments

Name	Type	Description
`borrows self`	`Array<T>`

Returns

Type	Description
`soa.Span<T> borrows (self)`

`write`#

write: function(
    exclusive self: Array<T>
): affine(soa.WriteToken & soa.WriteSpan<T>, soa.destroyWriteSpan) borrows (self)

Borrows the rows as an exclusive checked view.

Exclusive for as long as the writer is live, and affine, so a scope boundary or an explicit drop is what ends it.

Arguments

Name	Type	Description
`exclusive self`	`Array<T>`

Returns

Type	Description
`affine(soa.WriteToken & soa.WriteSpan<T>, soa.destroyWriteSpan) borrows (self)`

`close`#

close: nosuspend function(takes self: Array<T>): nil

Frees the slab. drop and scope exit both reach this.

Arguments

Name	Type	Description
`takes self`	`Array<T>`

Returns

Type	Description
`nil`

`drop`#

drop: nosuspend function(takes self: Array<T>): nil

Arguments

Name	Type	Description
`takes self`	`Array<T>`

Returns

Type	Description
`nil`

Fields

`count`#

count: integer

How many rows the slab holds.

`fingerprint`#

fingerprint: string

The layout fingerprint the slab was allocated under.

`ArrayToken`interface#

sealed interface soa.ArrayToken
    close: nosuspend function(takes self: ArrayToken): nil
end

Methods

`close`#

close: nosuspend function(takes self: ArrayToken): nil

Arguments

Name	Type	Description
`takes self`	`ArrayToken`

Returns

Type	Description
`nil`

`FieldLayout`record#

record soa.FieldLayout
    readonly name: string
    readonly identity: string
    readonly ctype: string
    readonly ordinal: integer
    readonly elementSize: integer
    readonly alignment: integer
end

One stored top-level field in a SoA descriptor.

Fields

`name`#

name: string

The field's name, as the struct declared it.

`identity`#

identity: string

The struct name and the field name joined, which is what a fingerprint entry is filed under.

`ctype`#

ctype: string

The C type of one element of this column.

`ordinal`#

ordinal: integer

Where this field sits in the declaration, counted from one.

`elementSize`#

elementSize: integer

Bytes per element.

`alignment`#

alignment: integer

The alignment the column starts on.

`InstanceLayout`record#

record soa.InstanceLayout
    readonly count: integer
    readonly byteSize: integer
    readonly segments: {soa.SegmentLayout}
end

The count-dependent layout of one complete SoA slab.

Fields

`count`#

count: integer

The row count this layout was computed for.

`byteSize`#

byteSize: integer

The slab's size in bytes, before alignment padding.

`segments`#

segments: {soa.SegmentLayout}

One segment per field, in declaration order.

`Layout`record#

record soa.Layout
    readonly name: string
    readonly fingerprint: string
    readonly alignment: integer
    readonly fields: {soa.FieldLayout}
    function forCount(self, count: integer): soa.InstanceLayout end
end

Immutable reflection for a reified struct's SoA representation.

Methods

`forCount`#

forCount: function forCount(self, count: integer): soa.InstanceLayout

Computes checked segment offsets for count rows without allocating storage.

Arguments

Name	Type	Description
`self`	`any`
`count`	`integer`

Returns

Type	Description
`soa.InstanceLayout`

Raises

when count is negative or the slab size overflows a Lua integer

Fields

`name`#

name: string

The struct's name.

`fingerprint`#

fingerprint: string

Every field's identity, type, size and alignment in one string, so two layouts can be compared without walking them.

`alignment`#

alignment: integer

The alignment the whole slab starts on, which is the widest field's.

`fields`#

fields: {soa.FieldLayout}

One entry per stored top-level field, in declaration order.

`SegmentLayout`record#

record soa.SegmentLayout
    readonly field: soa.FieldLayout
    readonly offset: integer
    readonly byteCount: integer
end

One field segment for a particular element count.

Fields

`field`#

field: soa.FieldLayout

Which field this segment holds.

`offset`#

offset: integer

Where the segment starts, in bytes from the slab's aligned base.

`byteCount`#

byteCount: integer

How many bytes it occupies.

`Span`interface#

sealed interface soa.Span<T>
    metamethod __len: function(self: Span<T>): integer
    metamethod __index: function(borrows self: Span<T>, index: integer): T
    slice: function(borrows self: Span<T>, first: integer, last: integer?): soa.Span<T> borrows (self)
    field: function(borrows self: Span<T>, name: string): any borrows (self)
end

A shared checked view over SoA rows.

Type parameters

Name	Description
`T`

Methods

`__len`#

__len: function(self: Span<T>): integer

Arguments

Name	Type	Description
`self`	`Span<T>`

Returns

Type	Description
`integer`

`__index`#

__index: function(borrows self: Span<T>, index: integer): T

Arguments

Name	Type	Description
`borrows self`	`Span<T>`
`index`	`integer`

Returns

Type	Description
`T`

`slice`#

slice: function(borrows self: Span<T>, first: integer, last: integer?): soa.Span<T> borrows (self)

Answers a subrange of rows, inclusive at both ends.

The result borrows this view, and omitting last runs through to the end.

Arguments

Name	Type	Description
`borrows self`	`Span<T>`
`first`	`integer`
`last`	`integer?`

Returns

Type	Description
`soa.Span<T> borrows (self)`

`field`#

field: function(borrows self: Span<T>, name: string): any borrows (self)

Answers one field's column as a nupp.mem.span view over this range.

The name must be a string literal naming a stored field, which is what lets the checker give the result that field's element type rather than any. A dynamic string or a missing field reports NUPP2403.

const rows = positions:read()
const velocity: span.Span<float> = rows:field("velocity")
for index = 1, #velocity do
    print(velocity[index])
end

Arguments

Name	Type	Description
`borrows self`	`Span<T>`
`name`	`string`

Returns

Type	Description
`any borrows (self)`

`Writable`type#

type soa.Writable<T> = affine(soa.WriteToken & soa.WriteSpan<T>, soa.destroyWriteSpan)

An affine exclusive row view, released at its lexical boundary.

Type parameters

Name	Description
`T`

`WriteSpan`interface#

sealed interface soa.WriteSpan<T>
    metamethod __len: function(self: WriteSpan<T>): integer
    metamethod __index: function(borrows self: WriteSpan<T>, index: integer): T
    metamethod __newindex: function(exclusive self: WriteSpan<T>, index: integer, value: T): nil
    field: function(exclusive self: WriteSpan<T>, name: string): any borrows (self)
    shared: function(borrows self: WriteSpan<T>): soa.Span<T> borrows (self)
    copyFrom: function(
        exclusive self: WriteSpan<T>,
        targetFirst: integer,
        borrows source: soa.Span<T>,
        sourceFirst: integer,
        count: integer
    ): nil
    slice: function(
        exclusive self: WriteSpan<T>,
        first: integer,
        last: integer?
    ): affine(soa.WriteToken & soa.WriteSpan<T>, soa.destroyWriteSpan) borrows (self)
end

An affine exclusive checked view over SoA rows.

Type parameters

Name	Description
`T`

Methods

`__len`#

__len: function(self: WriteSpan<T>): integer

Arguments

Name	Type	Description
`self`	`WriteSpan<T>`

Returns

Type	Description
`integer`

`__index`#

__index: function(borrows self: WriteSpan<T>, index: integer): T

Arguments

Name	Type	Description
`borrows self`	`WriteSpan<T>`
`index`	`integer`

Returns

Type	Description
`T`

`__newindex`#

__newindex: function(exclusive self: WriteSpan<T>, index: integer, value: T): nil

Arguments

Name	Type	Description
`exclusive self`	`WriteSpan<T>`
`index`	`integer`
`value`	`T`

Returns

Type	Description
`nil`

`field`#

field: function(exclusive self: WriteSpan<T>, name: string): any borrows (self)

Answers one field's column as a writable nupp.mem.span view.

Two different fields may be projected at once, because the columns do not overlap. The name must be a string literal naming a stored field; a dynamic string or a missing field reports NUPP2403.

do
    local rows = particles:write()
    local xs: span.Writable<float> = rows:field("x")
    local ys: span.Writable<float> = rows:field("y")
    xs[1] = 3.5
    ys[1] = 4.5
    drop xs
    drop ys
    drop rows
end

Arguments

Name	Type	Description
`exclusive self`	`WriteSpan<T>`
`name`	`string`

Returns

Type	Description
`any borrows (self)`

`shared`#

shared: function(borrows self: WriteSpan<T>): soa.Span<T> borrows (self)

Downgrades this writer to a shared row view for the lifetime of the result.

Arguments

Name	Type	Description
`borrows self`	`WriteSpan<T>`

Returns

Type	Description
`soa.Span<T> borrows (self)`

`copyFrom`#

copyFrom: function(
    exclusive self: WriteSpan<T>,
    targetFirst: integer,
    borrows source: soa.Span<T>,
    sourceFirst: integer,
    count: integer
): nil

Copies a row range from another view of the same struct.

Both ranges are checked before the first byte moves, and the copy is one contiguous run per column rather than a row at a time, so no row struct is ever materialized.

with rows = target:write() do
    rows:copyFrom(3, source:read(), 1, 2)
end

Arguments

Name	Type	Description
`exclusive self`	`WriteSpan<T>`
`targetFirst`	`integer`
`borrows source`	`soa.Span<T>`
`sourceFirst`	`integer`
`count`	`integer`

Returns

Type	Description
`nil`

`slice`#

slice: function(
    exclusive self: WriteSpan<T>,
    first: integer,
    last: integer?
): affine(soa.WriteToken & soa.WriteSpan<T>, soa.destroyWriteSpan) borrows (self)

Answers an affine writable subrange of rows, inclusive at both ends.

The child borrows this view, so the parent is unusable until the child is dropped. Row indexes start at one in the child, as they do in the parent.

Arguments

Name	Type	Description
`exclusive self`	`WriteSpan<T>`
`first`	`integer`
`last`	`integer?`

Returns

Type	Description
`affine(soa.WriteToken & soa.WriteSpan<T>, soa.destroyWriteSpan) borrows (self)`

`WriteToken`interface#

sealed interface soa.WriteToken
    drop: nosuspend function(takes self: WriteToken): nil
end

Methods

`drop`#

drop: nosuspend function(takes self: WriteToken): nil

Arguments

Name	Type	Description
`takes self`	`WriteToken`

Returns

Type	Description
`nil`

Functions#

`soa.allocate`function#

function soa.allocate<T>(element: ctype<T>, count: integer): affine(soa.Array<T>, soa.destroyArray)

Allocates one SoA slab for a reified struct type.

The compiler injects the descriptor, and aliases of this exact function retain the intrinsic identity. The result owns the slab and frees it at its lexical boundary; the bytes are not zeroed.

local positions = soa.allocate(ffi.typeof<Position>(), 128)
with rows = positions:write() do
    rows[1].x = 3.5
end

Type parameters

Name	Description
`T`

Arguments

Name	Type	Description
`element`	`ctype<T>`	the ctype of one row
`count`	`integer`	how many rows to allocate

Returns

Type	Description
`affine(soa.Array<T>, soa.destroyArray)`	the slab, owned by the caller

Raises

when count is negative, layout arithmetic overflows, or allocation fails

`soa.destroyArray`function#

function soa.destroyArray<T is soa.ArrayToken>(takes self: T): nil

Frees a slab, which is what every SoA array's contract names.

Nothing calls this by hand. It is the terminal consumer affine carries, so a scope boundary or an explicit drop reaches it.

Type parameters

Name	Description
`T`

Arguments

Name	Type	Description
`takes self`	`T`	the array, spent by this call

Returns

Type	Description
`nil`

`soa.destroyWriteSpan`function#

function soa.destroyWriteSpan<T is soa.WriteToken>(takes self: T): nil

Ends a row writer, which is what every writable row view's contract names.

Nothing calls this by hand. It is the terminal consumer affine carries, so a scope boundary or an explicit drop reaches it.

Type parameters

Name	Description
`T`

Arguments

Name	Type	Description
`takes self`	`T`	the writer, spent by this call

Returns

Type	Description
`nil`

`soa.layoutof`function#

function soa.layoutof<T>(element: ctype<T>): soa.Layout

Answers immutable SoA reflection for a reified struct type without allocating.

Only top-level fields are split, so a nested struct or fixed array is one field here whatever it holds.

local layout = soa.layoutof(ffi.typeof<Sample>())
assert(#layout.fields == 2)
assert(layout.fields[1].name == "position")

Type parameters

Name	Description
`T`

Arguments

Name	Type	Description
`element`	`ctype<T>`	the ctype of one row

Returns

Type	Description
`soa.Layout`	the count-independent descriptor

Raises

when compiler lowering is unavailable

nupp.mem.soa

Module contents

Types

Functions

Types#

Arrayrecord#

Type parameters

Methods

read#

Arguments

Returns

write#

Arguments

Returns

close#

Arguments

Returns

drop#

Arguments

Returns

Fields

count#

fingerprint#

ArrayTokeninterface#

Methods

close#

Arguments

Returns

FieldLayoutrecord#

Fields

name#

identity#

ctype#

ordinal#

elementSize#

alignment#

InstanceLayoutrecord#

Fields

count#

byteSize#

segments#

Layoutrecord#

Methods

forCount#

Arguments

Returns

Raises

Fields

name#

fingerprint#

alignment#

fields#

SegmentLayoutrecord#

Fields

field#

offset#

byteCount#

Spaninterface#

Type parameters

Methods

__len#

Arguments

Returns

__index#

Arguments

Returns

slice#

Arguments

Returns

field#

Arguments

Returns

Writabletype#

Type parameters

WriteSpaninterface#

Type parameters

Methods

__len#

Arguments

Returns

`nupp.mem.soa`

`Array`record#

`read`#

`write`#

`close`#

`drop`#

`count`#

`fingerprint`#

`ArrayToken`interface#

`close`#

`FieldLayout`record#

`name`#

`identity`#

`ctype`#

`ordinal`#

`elementSize`#

`alignment`#

`InstanceLayout`record#

`count`#

`byteSize`#

`segments`#

`Layout`record#

`forCount`#

`name`#

`fingerprint`#

`alignment`#

`fields`#

`SegmentLayout`record#

`field`#

`offset`#

`byteCount`#

`Span`interface#

`__len`#

`__index`#

`slice`#

`field`#

`Writable`type#

`WriteSpan`interface#

`__len`#

`__index`#

`__newindex`#

`field`#

`shared`#

`copyFrom`#

`slice`#

`WriteToken`interface#

`drop`#

`soa.allocate`function#

`soa.destroyArray`function#

`soa.destroyWriteSpan`function#

`soa.layoutof`function#