nupp.simd

Module contents

Types

TypeKindDescription
BlockU8x64interfaceFour adjacent preferred-width registers covering exactly 64 bytes.
MaskBits64interfaceA target-independent 64-bit predicate bitmap.
MaskU8interfaceOne predicate bit per logical vector lane.
PaddedStringU8interfaceA rooted string split into complete blocks and one zero-padded final block.
SpeciesU8interfaceThe preferred register-sized operation set for one element type.
TableU8x16interfaceOne immutable 16-byte lookup table embedded in generated native code.
VectorU8interfaceOne immutable packed value for the preferred target species.

Functions

FunctionKindDescription
alignBytesfunctionAligns previous ..
maskBits64functionCombines low and high uint32 words into an 64-bit mask.
paddedStringU8functionRoots a Lua string and prepares its one incomplete preferred-width block.
preferredU8functionSelects the artifact tier's preferred packed byte species.
paddedBytesU8functionRoots either a Lua string or a borrowed string buffer for a padded read.
storeInterleaved4functionWrites four registers interleaved into a byte scratch.
tableU8x16functionEmbeds one immutable 16-byte lookup table in an AOT entry.

Types#

BlockU8x64interface#

sealed interface simd.BlockU8x64
    andByte: function(borrows self: BlockU8x64, value: uint32): simd.BlockU8x64

    andBits: function(borrows self: BlockU8x64, other: BlockU8x64): simd.BlockU8x64
    shiftRight: function(borrows self: BlockU8x64, count: uint32): simd.BlockU8x64
    lookup16: function(borrows self: BlockU8x64, table: simd.TableU8x16): simd.BlockU8x64
    anyBitsSet: function(borrows self: BlockU8x64, value: uint32): simd.MaskBits64
    lastVector: function(borrows self: BlockU8x64): simd.VectorU8
    utf8Errors: function(
        borrows self: BlockU8x64,
        previous: simd.VectorU8,
        byte1High: simd.TableU8x16,
        byte1Low: simd.TableU8x16,
        byte2High: simd.TableU8x16
    ): simd.MaskBits64

    equal: function(borrows self: BlockU8x64, value: uint32): simd.MaskBits64
    equalAny6: function(
        borrows self: BlockU8x64,
        v0: uint32,
        v1: uint32,
        v2: uint32,
        v3: uint32,
        v4: uint32,
        v5: uint32
    ): simd.MaskBits64
    inRange: function(borrows self: BlockU8x64, low: uint32, high: uint32): simd.MaskBits64
    outsideRange: function(borrows self: BlockU8x64, low: uint32, high: uint32): simd.MaskBits64
end

Four adjacent preferred-width registers covering exactly 64 bytes.

Block comparisons return one target-independent bitmap, so scanners can classify a cache-line-sized unit without publishing intermediate register masks through scalar Nupp values.

Methods

andByte#
andByte: function(borrows self: BlockU8x64, value: uint32): simd.BlockU8x64

Applies one byte mask to every lane in all four registers.

Arguments
NameTypeDescription
borrows selfBlockU8x64
valueuint32
Returns
TypeDescription
simd.BlockU8x64
andBits#
andBits: function(borrows self: BlockU8x64, other: BlockU8x64): simd.BlockU8x64
Arguments
NameTypeDescription
borrows selfBlockU8x64
otherBlockU8x64
Returns
TypeDescription
simd.BlockU8x64
shiftRight#
shiftRight: function(borrows self: BlockU8x64, count: uint32): simd.BlockU8x64
Arguments
NameTypeDescription
borrows selfBlockU8x64
countuint32
Returns
TypeDescription
simd.BlockU8x64
lookup16#
lookup16: function(borrows self: BlockU8x64, table: simd.TableU8x16): simd.BlockU8x64

Looks up every lane in the same immutable 16-byte table.

Arguments
NameTypeDescription
borrows selfBlockU8x64
tablesimd.TableU8x16
Returns
TypeDescription
simd.BlockU8x64
anyBitsSet#
anyBitsSet: function(borrows self: BlockU8x64, value: uint32): simd.MaskBits64

Returns one bit for each lane having any bit in value set.

Arguments
NameTypeDescription
borrows selfBlockU8x64
valueuint32
Returns
TypeDescription
simd.MaskBits64
lastVector#
lastVector: function(borrows self: BlockU8x64): simd.VectorU8

Returns the final preferred-width register for cross-block carry.

Arguments
NameTypeDescription
borrows selfBlockU8x64
Returns
TypeDescription
simd.VectorU8
utf8Errors#
utf8Errors: function(
    borrows self: BlockU8x64,
    previous: simd.VectorU8,
    byte1High: simd.TableU8x16,
    byte1Low: simd.TableU8x16,
    byte2High: simd.TableU8x16
): simd.MaskBits64

Applies the lookup4 UTF-8 validator across the whole block.

previous is the final preferred-width register before this block. The three tables are the high and low nibble classes for byte one and the high nibble classes for byte two. Set result bits identify invalid byte positions in this block.

Arguments
NameTypeDescription
borrows selfBlockU8x64
previoussimd.VectorU8
byte1Highsimd.TableU8x16
byte1Lowsimd.TableU8x16
byte2Highsimd.TableU8x16
Returns
TypeDescription
simd.MaskBits64
equal#
equal: function(borrows self: BlockU8x64, value: uint32): simd.MaskBits64
Arguments
NameTypeDescription
borrows selfBlockU8x64
valueuint32
Returns
TypeDescription
simd.MaskBits64
equalAny6#
equalAny6: function(
    borrows self: BlockU8x64,
    v0: uint32,
    v1: uint32,
    v2: uint32,
    v3: uint32,
    v4: uint32,
    v5: uint32
): simd.MaskBits64
Arguments
NameTypeDescription
borrows selfBlockU8x64
v0uint32
v1uint32
v2uint32
v3uint32
v4uint32
v5uint32
Returns
TypeDescription
simd.MaskBits64
inRange#
inRange: function(borrows self: BlockU8x64, low: uint32, high: uint32): simd.MaskBits64
Arguments
NameTypeDescription
borrows selfBlockU8x64
lowuint32
highuint32
Returns
TypeDescription
simd.MaskBits64
outsideRange#
outsideRange: function(borrows self: BlockU8x64, low: uint32, high: uint32): simd.MaskBits64
Arguments
NameTypeDescription
borrows selfBlockU8x64
lowuint32
highuint32
Returns
TypeDescription
simd.MaskBits64

MaskBits64interface#

sealed interface simd.MaskBits64
    add: function(borrows self: MaskBits64, other: MaskBits64): simd.MaskBits64

    andBits: function(borrows self: MaskBits64, other: MaskBits64): simd.MaskBits64
    orBits: function(borrows self: MaskBits64, other: MaskBits64): simd.MaskBits64
    xorBits: function(borrows self: MaskBits64, other: MaskBits64): simd.MaskBits64
    notBits: function(borrows self: MaskBits64): simd.MaskBits64
    shiftLeft: function(borrows self: MaskBits64, count: uint32): simd.MaskBits64
    shiftRight: function(borrows self: MaskBits64, count: uint32): simd.MaskBits64
    prefixXor: function(borrows self: MaskBits64, carry: boolean): simd.MaskBits64
    lowBits: function(borrows self: MaskBits64): uint32
    highBits: function(borrows self: MaskBits64): uint32
    any: function(borrows self: MaskBits64): boolean
    count: function(borrows self: MaskBits64): uint32
    firstSet: function(borrows self: MaskBits64): uint32
    clearFirst: function(borrows self: MaskBits64): simd.MaskBits64
end

A target-independent 64-bit predicate bitmap.

This is deliberately not a general uint64: ordinary Nupp numbers retain their LuaJIT representation and exactness rules. The two uint32 halves let scanners combine register masks, carry prefix state across them, and drain events without boxing cdata.

Methods

add#
add: function(borrows self: MaskBits64, other: MaskBits64): simd.MaskBits64

Adds with carry across the word boundary.

Present because run-parity over a block is stated as an addition: adding a run's start bit to the run propagates a carry to the first bit past its end, which is how a scanner tells an odd run of escapes from an even one without walking the runs. Nothing else here carries between words.

Arguments
NameTypeDescription
borrows selfMaskBits64
otherMaskBits64
Returns
TypeDescription
simd.MaskBits64
andBits#
andBits: function(borrows self: MaskBits64, other: MaskBits64): simd.MaskBits64
Arguments
NameTypeDescription
borrows selfMaskBits64
otherMaskBits64
Returns
TypeDescription
simd.MaskBits64
orBits#
orBits: function(borrows self: MaskBits64, other: MaskBits64): simd.MaskBits64
Arguments
NameTypeDescription
borrows selfMaskBits64
otherMaskBits64
Returns
TypeDescription
simd.MaskBits64
xorBits#
xorBits: function(borrows self: MaskBits64, other: MaskBits64): simd.MaskBits64
Arguments
NameTypeDescription
borrows selfMaskBits64
otherMaskBits64
Returns
TypeDescription
simd.MaskBits64
notBits#
notBits: function(borrows self: MaskBits64): simd.MaskBits64
Arguments
NameTypeDescription
borrows selfMaskBits64
Returns
TypeDescription
simd.MaskBits64
shiftLeft#
shiftLeft: function(borrows self: MaskBits64, count: uint32): simd.MaskBits64
Arguments
NameTypeDescription
borrows selfMaskBits64
countuint32
Returns
TypeDescription
simd.MaskBits64
shiftRight#
shiftRight: function(borrows self: MaskBits64, count: uint32): simd.MaskBits64
Arguments
NameTypeDescription
borrows selfMaskBits64
countuint32
Returns
TypeDescription
simd.MaskBits64
prefixXor#
prefixXor: function(borrows self: MaskBits64, carry: boolean): simd.MaskBits64
Arguments
NameTypeDescription
borrows selfMaskBits64
carryboolean
Returns
TypeDescription
simd.MaskBits64
lowBits#
lowBits: function(borrows self: MaskBits64): uint32
Arguments
NameTypeDescription
borrows selfMaskBits64
Returns
TypeDescription
uint32
highBits#
highBits: function(borrows self: MaskBits64): uint32
Arguments
NameTypeDescription
borrows selfMaskBits64
Returns
TypeDescription
uint32
any#
any: function(borrows self: MaskBits64): boolean
Arguments
NameTypeDescription
borrows selfMaskBits64
Returns
TypeDescription
boolean
count#
count: function(borrows self: MaskBits64): uint32
Arguments
NameTypeDescription
borrows selfMaskBits64
Returns
TypeDescription
uint32
firstSet#
firstSet: function(borrows self: MaskBits64): uint32
Arguments
NameTypeDescription
borrows selfMaskBits64
Returns
TypeDescription
uint32
clearFirst#
clearFirst: function(borrows self: MaskBits64): simd.MaskBits64
Arguments
NameTypeDescription
borrows selfMaskBits64
Returns
TypeDescription
simd.MaskBits64

MaskU8interface#

sealed interface simd.MaskU8
    andBits: function(borrows self: MaskU8, other: MaskU8): simd.MaskU8
    orBits: function(borrows self: MaskU8, other: MaskU8): simd.MaskU8
    xorBits: function(borrows self: MaskU8, other: MaskU8): simd.MaskU8
    notBits: function(borrows self: MaskU8): simd.MaskU8
    select: function(borrows self: MaskU8, whenTrue: simd.VectorU8, whenFalse: simd.VectorU8): simd.VectorU8
    any: function(borrows self: MaskU8): boolean
    all: function(borrows self: MaskU8): boolean
    count: function(borrows self: MaskU8): uint32
    bits: function(borrows self: MaskU8): uint32
end

One predicate bit per logical vector lane.

Methods

andBits#
andBits: function(borrows self: MaskU8, other: MaskU8): simd.MaskU8
Arguments
NameTypeDescription
borrows selfMaskU8
otherMaskU8
Returns
TypeDescription
simd.MaskU8
orBits#
orBits: function(borrows self: MaskU8, other: MaskU8): simd.MaskU8
Arguments
NameTypeDescription
borrows selfMaskU8
otherMaskU8
Returns
TypeDescription
simd.MaskU8
xorBits#
xorBits: function(borrows self: MaskU8, other: MaskU8): simd.MaskU8
Arguments
NameTypeDescription
borrows selfMaskU8
otherMaskU8
Returns
TypeDescription
simd.MaskU8
notBits#
notBits: function(borrows self: MaskU8): simd.MaskU8
Arguments
NameTypeDescription
borrows selfMaskU8
Returns
TypeDescription
simd.MaskU8
select#
select: function(borrows self: MaskU8, whenTrue: simd.VectorU8, whenFalse: simd.VectorU8): simd.VectorU8
Arguments
NameTypeDescription
borrows selfMaskU8
whenTruesimd.VectorU8
whenFalsesimd.VectorU8
Returns
TypeDescription
simd.VectorU8
any#
any: function(borrows self: MaskU8): boolean
Arguments
NameTypeDescription
borrows selfMaskU8
Returns
TypeDescription
boolean
all#
all: function(borrows self: MaskU8): boolean
Arguments
NameTypeDescription
borrows selfMaskU8
Returns
TypeDescription
boolean
count#
count: function(borrows self: MaskU8): uint32
Arguments
NameTypeDescription
borrows selfMaskU8
Returns
TypeDescription
uint32
bits#
bits: function(borrows self: MaskU8): uint32
Arguments
NameTypeDescription
borrows selfMaskU8
Returns
TypeDescription
uint32

PaddedStringU8interface#

sealed interface simd.PaddedStringU8
    readonly length: uint32
    readonly fullLength: uint32
    readonly tailLength: uint32
    loadFull: function(borrows self: PaddedStringU8, offset: uint32): simd.VectorU8
    loadTail: function(borrows self: PaddedStringU8): simd.VectorU8
    loadBlock64: function(borrows self: PaddedStringU8, offset: uint32): simd.BlockU8x64
end

A rooted string split into complete blocks and one zero-padded final block. The view exists only for the duration of its AOT entry.

Methods

loadFull#
loadFull: function(borrows self: PaddedStringU8, offset: uint32): simd.VectorU8

Loads a complete block. The offset must be below fullLength and aligned to the preferred species width.

Arguments
NameTypeDescription
borrows selfPaddedStringU8
offsetuint32
Returns
TypeDescription
simd.VectorU8
loadTail#
loadTail: function(borrows self: PaddedStringU8): simd.VectorU8

Loads the sole incomplete block, already copied and zero padded.

Arguments
NameTypeDescription
borrows selfPaddedStringU8
Returns
TypeDescription
simd.VectorU8
loadBlock64#
loadBlock64: function(borrows self: PaddedStringU8, offset: uint32): simd.BlockU8x64

Loads 64 complete bytes at an aligned offset. An unavailable block is zero, on the same defensive terms as loadFull; scanners normally call this only after proving offset + 64 <= length.

Arguments
NameTypeDescription
borrows selfPaddedStringU8
offsetuint32
Returns
TypeDescription
simd.BlockU8x64

Fields

length#
length: uint32
fullLength#
fullLength: uint32
tailLength#
tailLength: uint32

SpeciesU8interface#

sealed interface simd.SpeciesU8
    readonly lanes: integer
    splat: function(borrows self: SpeciesU8, value: uint32): simd.VectorU8
    load: function(borrows self: SpeciesU8, borrows source: Span<uint8>, offset: integer): simd.VectorU8
    loadString: function(borrows self: SpeciesU8, source: string, offset: integer): simd.VectorU8
    loadStrided3: function(borrows self: SpeciesU8, source: string, offset: uint32, lane: uint32): simd.VectorU8
    tail: function(borrows self: SpeciesU8, active: integer): simd.MaskU8
end

The preferred register-sized operation set for one element type.

Methods

splat#
splat: function(borrows self: SpeciesU8, value: uint32): simd.VectorU8

Broadcasts the low byte of value to every lane.

Arguments
NameTypeDescription
borrows selfSpeciesU8
valueuint32
Returns
TypeDescription
simd.VectorU8
load#
load: function(borrows self: SpeciesU8, borrows source: Span<uint8>, offset: integer): simd.VectorU8

Loads at a zero-based offset. Inactive final lanes are zero and are excluded by tail; the implementation never reads beyond the span.

Arguments
NameTypeDescription
borrows selfSpeciesU8
borrows sourceSpan<uint8>
offsetinteger
Returns
TypeDescription
simd.VectorU8
loadString#
loadString: function(borrows self: SpeciesU8, source: string, offset: integer): simd.VectorU8

Loads directly from a string rooted by a Lua-builder AOT entry. This is the VM-aware counterpart of load: storage remains owned and pinned by Lua for the duration of the native call.

Arguments
NameTypeDescription
borrows selfSpeciesU8
sourcestring
offsetinteger
Returns
TypeDescription
simd.VectorU8
loadStrided3#
loadStrided3: function(borrows self: SpeciesU8, source: string, offset: uint32, lane: uint32): simd.VectorU8

Loads one lane of a three-byte interleaved group from a rooted string.

lane selects which byte of each group is collected: 0 gathers bytes 0, 3, 6 and so on, 1 gathers 1, 4, 7, and 2 gathers 2, 5, 8. Three calls at the same offset therefore de-interleave 3 * lanes bytes into three registers, which is the shape a codec over three-byte groups wants and the shape aarch64's ld3 already produces.

A group that would read past the string contributes zero, on the same defensive terms as the other loads here.

Arguments
NameTypeDescription
borrows selfSpeciesU8
sourcestring
offsetuint32
laneuint32
Returns
TypeDescription
simd.VectorU8
tail#
tail: function(borrows self: SpeciesU8, active: integer): simd.MaskU8

A mask with the first active lanes set, clamped to this species.

Arguments
NameTypeDescription
borrows selfSpeciesU8
activeinteger
Returns
TypeDescription
simd.MaskU8

Fields

lanes#
lanes: integer

TableU8x16interface#

sealed interface simd.TableU8x16
end

One immutable 16-byte lookup table embedded in generated native code.

VectorU8interface#

sealed interface simd.VectorU8
    equal: function(borrows self: VectorU8, value: uint32): simd.MaskU8
    inRange: function(borrows self: VectorU8, low: uint32, high: uint32): simd.MaskU8
    andBits: function(borrows self: VectorU8, other: VectorU8): simd.VectorU8
    orBits: function(borrows self: VectorU8, other: VectorU8): simd.VectorU8
    xorBits: function(borrows self: VectorU8, other: VectorU8): simd.VectorU8
    notBits: function(borrows self: VectorU8): simd.VectorU8
    shiftRight: function(borrows self: VectorU8, count: uint32): simd.VectorU8
    shiftLeft: function(borrows self: VectorU8, count: uint32): simd.VectorU8
    lookup16: function(borrows self: VectorU8, table: simd.TableU8x16): simd.VectorU8
    lookup64: function(
        borrows self: VectorU8,
        low: simd.TableU8x16,
        lowMid: simd.TableU8x16,
        highMid: simd.TableU8x16,
        high: simd.TableU8x16
    ): simd.VectorU8
end

One immutable packed value for the preferred target species.

Methods

equal#
equal: function(borrows self: VectorU8, value: uint32): simd.MaskU8
Arguments
NameTypeDescription
borrows selfVectorU8
valueuint32
Returns
TypeDescription
simd.MaskU8
inRange#
inRange: function(borrows self: VectorU8, low: uint32, high: uint32): simd.MaskU8
Arguments
NameTypeDescription
borrows selfVectorU8
lowuint32
highuint32
Returns
TypeDescription
simd.MaskU8
andBits#
andBits: function(borrows self: VectorU8, other: VectorU8): simd.VectorU8
Arguments
NameTypeDescription
borrows selfVectorU8
otherVectorU8
Returns
TypeDescription
simd.VectorU8
orBits#
orBits: function(borrows self: VectorU8, other: VectorU8): simd.VectorU8
Arguments
NameTypeDescription
borrows selfVectorU8
otherVectorU8
Returns
TypeDescription
simd.VectorU8
xorBits#
xorBits: function(borrows self: VectorU8, other: VectorU8): simd.VectorU8
Arguments
NameTypeDescription
borrows selfVectorU8
otherVectorU8
Returns
TypeDescription
simd.VectorU8
notBits#
notBits: function(borrows self: VectorU8): simd.VectorU8
Arguments
NameTypeDescription
borrows selfVectorU8
Returns
TypeDescription
simd.VectorU8
shiftRight#
shiftRight: function(borrows self: VectorU8, count: uint32): simd.VectorU8
Arguments
NameTypeDescription
borrows selfVectorU8
countuint32
Returns
TypeDescription
simd.VectorU8
shiftLeft#
shiftLeft: function(borrows self: VectorU8, count: uint32): simd.VectorU8
Arguments
NameTypeDescription
borrows selfVectorU8
countuint32
Returns
TypeDescription
simd.VectorU8
lookup16#
lookup16: function(borrows self: VectorU8, table: simd.TableU8x16): simd.VectorU8

Looks up every lane in one immutable 16-byte table. Indexes outside 0..15 produce zero, matching the native table instructions.

Arguments
NameTypeDescription
borrows selfVectorU8
tablesimd.TableU8x16
Returns
TypeDescription
simd.VectorU8
lookup64#
lookup64: function(
    borrows self: VectorU8,
    low: simd.TableU8x16,
    lowMid: simd.TableU8x16,
    highMid: simd.TableU8x16,
    high: simd.TableU8x16
): simd.VectorU8

Looks up every lane in four immutable 16-byte tables read as one 64-entry table. Indexes outside 0..63 produce zero.

Four tables rather than a 64-entry type because that is the shape the instruction takes: aarch64 spends one tbl on it, and it is the lookup a six-bit alphabet wants. On x86 it is built from the nibble lookup and a blend, which is what AVX-512 VBMI's vpermb exists to replace.

Arguments
NameTypeDescription
borrows selfVectorU8
lowsimd.TableU8x16
lowMidsimd.TableU8x16
highMidsimd.TableU8x16
highsimd.TableU8x16
Returns
TypeDescription
simd.VectorU8

Functions#

alignBytesfunction#

function alignBytes(previous: any, current: any, offset: number): any

Aligns previous .. current, bringing the last offset bytes of the previous vector into the beginning of the result. Offsets 1..3 are admitted because they are the cross-block lookback needed by UTF-8 scans.

Arguments

NameTypeDescription
previousany
currentany
offsetnumber

Returns

TypeDescription
any

maskBits64function#

function maskBits64(low: number, high: number): any

Combines low and high uint32 words into an 64-bit mask.

Arguments

NameTypeDescription
lownumber
highnumber

Returns

TypeDescription
any

paddedStringU8function#

function paddedStringU8(source: string): any

Roots a Lua string and prepares its one incomplete preferred-width block.

Arguments

NameTypeDescription
sourcestring

Returns

TypeDescription
any

preferredU8function#

function preferredU8(): any

Selects the artifact tier's preferred packed byte species.

Returns

TypeDescription
any

simd.paddedBytesU8function#

function simd.paddedBytesU8(borrows source: any): simd.PaddedStringU8

Roots either a Lua string or a borrowed string buffer for a padded read. This union exists only at a Lua-builder AOT boundary.

Arguments

NameTypeDescription
borrows sourceany

Returns

TypeDescription
simd.PaddedStringU8

Raises

  • outside an AOT-compiled function

simd.storeInterleaved4function#

function simd.storeInterleaved4(scratch: any, offset: uint32, first: simd.VectorU8, second: simd.VectorU8, third: simd.VectorU8, fourth: simd.VectorU8): nil

Writes four registers interleaved into a byte scratch.

Lane i of each register lands at offset + 4i through offset + 4i + 3, which is the inverse of the three-lane strided load and the shape a codec emitting four-byte groups produces. aarch64 spends one st4 on it.

Appends when offset is the scratch's current length and overwrites below it, on the same terms as nupp.codec.valuebuilder.setScratchBytes4.

Arguments

NameTypeDescription
scratchany
offsetuint32
firstsimd.VectorU8
secondsimd.VectorU8
thirdsimd.VectorU8
fourthsimd.VectorU8

Returns

TypeDescription
nil

Raises

  • outside an AOT-compiled function

tableU8x16function#

function tableU8x16(...): any

Embeds one immutable 16-byte lookup table in an AOT entry.

Arguments

NameTypeDescription
...any

Returns

TypeDescription
any