⌂ Modules nupp nupp.mem nupp.mem.soa nupp.mem.soaStructure-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.
Module contents Types Type Kind Description Arrayrecord An owned native slab whose top-level struct fields occupy separate segments. ArrayTokeninterface FieldLayoutrecord A stored top-level field in a SoA descriptor. InstanceLayoutrecord The count-dependent layout of a complete SoA slab. Layoutrecord Immutable reflection for a reified struct's SoA representation. ReadViewinterface A read-only SoA row view independent of its row type. SegmentLayoutrecord A field segment for a particular element count. Spaninterface A shared checked view over SoA rows. Writabletype An affine exclusive row view, released at its lexical boundary. WriteSpaninterface An affine exclusive checked view over SoA rows. WriteTokeninterface
Functions Function Kind Description allocatefunction Allocates a SoA slab for a reified struct type. destroyArrayfunction Frees a slab, which is what every SoA array's contract names. destroyWriteSpanfunction Ends a row writer, which is what every writable row view's contract names. layoutoffunction Returns immutable SoA reflection for a reified struct type without allocating.
Types
Arrayrecord An owned native slab whose top-level struct fields occupy separate segments.
Type parameters
Members Name Kind Description rawfield elementfield layoutfield columnsfield countfield How many rows the slab holds. fingerprintfield The layout fingerprint the slab was allocated under. readmethod Borrows the rows as a shared checked view. writemethod Borrows the rows as an exclusive checked view. closemethod Frees the slab.
elementfield @private @readonly
layoutfield @private @readonly
columnsfield @private @readonly
countfield @readonly
How many rows the slab holds.
fingerprintfield @readonly
The layout fingerprint the slab was allocated under.
readmethod 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 selfArray < T >
Returns Type Description soa . Span < T > borrows ( self )
writemethod 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 nupp.drop is what ends it.
Arguments Name Type Description exclusive selfArray < T >
Returns
closemethod close : @ nosuspend function ( takes self : Array < T > ) : nil Frees the slab. nupp.drop and scope exit both reach this.
Arguments Name Type Description takes selfArray < T >
Returns
ArrayTokeninterface Members Name Kind Description closemethod
closemethod Arguments
Returns
FieldLayoutrecord A stored top-level field in a SoA descriptor.
Members Name Kind Description namefield The field's name, as the struct declared it. identityfield The struct name and the field name joined, which is what a fingerprint entry is filed under. ctypefield The C type of an element of this column. ordinalfield Where this field sits in the declaration, counted from one. elementSizefield Bytes per element. alignmentfield The alignment the column starts on. pointerTypefield
namefield @readonly
The field's name, as the struct declared it.
identityfield @readonly
The struct name and the field name joined, which is what a fingerprint entry is filed under.
ctypefield @readonly
The C type of an element of this column.
ordinalfield @readonly
Where this field sits in the declaration, counted from one.
elementSizefield @readonly
Bytes per element.
alignmentfield @readonly
The alignment the column starts on.
pointerTypefield @private @readonly
InstanceLayoutrecord The count-dependent layout of a complete SoA slab.
Members Name Kind Description countfield The row count this layout was computed for. byteSizefield The slab's size in bytes, before alignment padding. segmentsfield One segment per field, in declaration order.
countfield @readonly
The row count this layout was computed for.
byteSizefield @readonly
The slab's size in bytes, before alignment padding.
segmentsfield @readonly
One segment per field, in declaration order.
Layoutrecord Immutable reflection for a reified struct's SoA representation.
Members Name Kind Description namefield The struct's name. fingerprintfield Every field's identity, type, size and alignment in one string, so two layouts can be compared without walking them. alignmentfield The alignment the whole slab starts on, which is the widest field's. fieldsfield One entry per stored top-level field, in declaration order. forCountmethod Computes checked segment offsets for count rows without allocating storage.
namefield @readonly
The struct's name.
fingerprintfield @readonly
Every field's identity, type, size and alignment in one string, so two layouts can be compared without walking them.
alignmentfield @readonly
The alignment the whole slab starts on, which is the widest field's.
fieldsfield @readonly
One entry per stored top-level field, in declaration order.
forCountmethod Computes checked segment offsets for count rows without allocating storage.
Arguments Name Type Description selfany countinteger
Returns
Raises Type Condition string when count is not a nonnegative integer or the slab size overflows
ReadViewinterface A read-only SoA row view independent of its row type.
SegmentLayoutrecord A field segment for a particular element count.
Members Name Kind Description fieldfield Which field this segment holds. offsetfield Where the segment starts, in bytes from the slab's aligned base. byteCountfield How many bytes it occupies.
fieldfield @readonly
Which field this segment holds.
offsetfield @readonly
Where the segment starts, in bytes from the slab's aligned base.
byteCountfield @readonly
How many bytes it occupies.
Spaninterface A shared checked view over SoA rows.
Project a column with rows.name. When a field name collides with a view member, use the literal bracket form rows["name"].
Type parameters
Members Name Kind Description __lenmetamethod __indexmetamethod slicemethod Returns a subrange of rows, inclusive at both ends.
__lenmetamethod __len : function ( self : Span < T > ) : integer Arguments Name Type Description selfSpan < T >
Returns
__indexmetamethod __index : function ( borrows self : Span < T > , index : integer ) : T Arguments Name Type Description borrows selfSpan < T > indexinteger
Returns
slicemethod slice : function ( borrows self : Span < T > , first : integer , last : integer ? ) : soa . Span < T > borrows ( self ) Returns 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 selfSpan < T > firstinteger lastinteger ?
Returns Type Description soa . Span < T > borrows ( self )
Writabletype An affine exclusive row view, released at its lexical boundary.
Type parameters
WriteSpaninterface An affine exclusive checked view over SoA rows.
Project a writable column with rows.name. When a field name collides with a view member, use the literal bracket form rows["name"].
Type parameters
Members Name Kind Description __lenmetamethod __indexmetamethod __newindexmetamethod sharedmethod Downgrades this writer to a shared row view for the lifetime of the result. copyFrommethod Copies a row range from another view of the same struct. slicemethod Returns an affine writable subrange of rows, inclusive at both ends.
__lenmetamethod Arguments
Returns
__indexmetamethod __index : function ( borrows self : WriteSpan < T > , index : integer ) : T Arguments Name Type Description borrows selfWriteSpan < T > indexinteger
Returns
__newindexmetamethod __newindex : function ( exclusive self : WriteSpan < T > , index : integer , value : T ) : nil Arguments Name Type Description exclusive selfWriteSpan < T > indexinteger valueT
Returns
sharedmethod 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
Returns Type Description soa . Span < T > borrows ( self )
copyFrommethod 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 selfWriteSpan < T > targetFirstinteger borrows sourcesoa . Span < T > sourceFirstinteger countinteger
Returns
slicemethod Returns 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 selfWriteSpan < T > firstinteger lastinteger ?
Returns
WriteTokeninterface Members Name Kind Description dropmethod
dropmethod drop : @ nosuspend function ( takes self : WriteToken ) : nil Arguments
Returns
Functions
soa.allocatefunction Allocates a 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
Arguments Name Type Description elementctype < T > the ctype of a row
countinteger how many rows to allocate
Returns
Raises Type Condition string when count is invalid, layout arithmetic overflows, or allocation fails
soa.destroyArrayfunction 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 nupp.drop reaches it.
Type parameters
Arguments Name Type Description takes selfT the array, spent by this call
Returns
soa.destroyWriteSpanfunction 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 nupp.drop reaches it.
Type parameters
Arguments Name Type Description takes selfT the writer, spent by this call
Returns
soa.layoutoffunction Returns immutable SoA reflection for a reified struct type without allocating.
Only top-level fields are split, so a nested struct or fixed array is a field here whatever it holds.
Type parameters
Arguments Name Type Description elementctype < T > the ctype of a row
Returns Type Description soa . Layout the count-independent descriptor
Raises Type Condition string when compiler lowering is unavailable
← Previous nupp.mem.sharedbytes Next → nupp.mem.span