`nupp.mem.sharedbytes`

Engine-owned immutable byte regions.

A region names an extent of one reference-counted engine block. It crosses worker boundaries by reference, slices without copying, and is read in place through a borrowed nupp.mem.span byte view; converting it to a Lua string is one explicit call. See NEP 20.

const sharedbytes = nupp.mem.sharedbytes

const region = sharedbytes.copy("hello, region")
const hello = region:slice(1, 5)
assert(hello:size() == 5 and hello:text() == "hello")

A producer that has bytes only behind a pointer writes into builder storage directly through a reserve-and-commit pair, with no intermediate chunk string:

const sharedbytes = nupp.mem.sharedbytes

local builder = sharedbytes.builder()
with writer = builder:reserve(5) do
    for index = 1, 5 do
        writer[index] = 64 + index
    end
end
builder:commit(5)
builder:append("!")
assert(builder:freeze():text() == "ABCDE!")

Module contents

Types

Type	Kind	Description
`Builder`	record	A growable engine allocation that becomes a region when frozen.
`BuilderToken`	interface	An affine accumulator of engine storage.
`Region`	record	An immutable extent of one engine-owned block.

Functions

Function	Kind	Description
`builder`	function	Opens an empty builder.
`copy`	function	Copies text once into an engine-owned region.
`readFile`	function	Reads a whole file directly into an engine-owned region, with no intermediate Lua string for the payload.

Types#

`Builder`record#

record sharedbytes.Builder is sharedbytes.BuilderToken
    append: nosuspend function(sharedbytes.Builder, string): nil
    reserve: function(exclusive self: sharedbytes.Builder, integer): span.Writable<uint8> borrows (self)
    commit: nosuspend function(sharedbytes.Builder, integer): nil
    freeze: nosuspend function(takes self: sharedbytes.Builder): sharedbytes.Region
    drop: nosuspend function(takes self: sharedbytes.Builder): nil
end

A growable engine allocation that becomes a region when frozen.

Methods

`append`#

append: nosuspend function(sharedbytes.Builder, string): nil

Appends the chunk's bytes to the builder's storage.

Arguments

Name	Type	Description
`?`	`sharedbytes.Builder`
`?`	`string`

Returns

Type	Description
`nil`

Raises

when a reservation is open or the engine cannot grow the storage

`reserve`#

reserve: function(exclusive self: sharedbytes.Builder, integer): span.Writable<uint8> borrows (self)

Grows the storage and lends a checked writer over exactly count uninitialized bytes past what is already committed. All growth happens here, before the writer exists, and the borrow keeps every other builder operation a compile error while the writer lives, so the lent pointer cannot be invalidated. One commit closes the reservation after the writer drops.

Arguments

Name	Type	Description
`exclusive self`	`sharedbytes.Builder`
`?`	`integer`

Returns

Type	Description
`span.Writable<uint8> borrows (self)`

Raises

when the count is negative, a reservation is already open, or the engine cannot grow the storage

`commit`#

commit: nosuspend function(sharedbytes.Builder, integer): nil

Closes the open reservation, keeping its first written bytes as content; a short read commits what arrived, and the surplus returns to capacity for the next reservation.

Arguments

Name	Type	Description
`?`	`sharedbytes.Builder`
`?`	`integer`

Returns

Type	Description
`nil`

Raises

when no reservation is open or written exceeds it

`freeze`#

freeze: nosuspend function(takes self: sharedbytes.Builder): sharedbytes.Region

Consumes the builder and transfers its allocation into a region.

Arguments

Name	Type	Description
`takes self`	`sharedbytes.Builder`

Returns

Type	Description
`sharedbytes.Region`

Raises

when the builder was already frozen or a reservation is open, because sealing would silently drop bytes a producer may have written

`drop`#

drop: nosuspend function(takes self: sharedbytes.Builder): nil

Releases an unfrozen builder's storage at scope exit.

Arguments

Name	Type	Description
`takes self`	`sharedbytes.Builder`

Returns

Type	Description
`nil`

`BuilderToken`interface#

affine interface sharedbytes.BuilderToken
    terminal drop: nosuspend function(takes self: sharedbytes.BuilderToken): nil
end

An affine accumulator of engine storage. Appending grows one private allocation, and freezing transfers it into a region without copying.

Methods

`drop`#

drop: nosuspend function(takes self: sharedbytes.BuilderToken): nil

Arguments

Name	Type	Description
`takes self`	`sharedbytes.BuilderToken`

Returns

Type	Description
`nil`

`Region`record#

record sharedbytes.Region
    size: nosuspend function(sharedbytes.Region): integer
    slice: function(sharedbytes.Region, integer, integer): sharedbytes.Region
    view: function(borrows self: sharedbytes.Region, integer?, integer?): span.ByteSpan borrows (self)
    viewAs: function<T>(borrows self: sharedbytes.Region, ctype<T>): span.Span<T> borrows (self)
    text: nosuspend function(sharedbytes.Region): string
end

An immutable extent of one engine-owned block. Crossing a worker boundary moves a reference, never the bytes; reading happens in place through a borrowed byte view, and text is the one explicit copy into a Lua state.

Methods

`size`#

size: nosuspend function(sharedbytes.Region): integer

How many bytes the region holds.

Arguments

Name	Type	Description
`?`	`sharedbytes.Region`

Returns

Type	Description
`integer`

`slice`#

slice: function(sharedbytes.Region, integer, integer): sharedbytes.Region

A zero-copy region over bytes first through last of this one.

Arguments

Name	Type	Description
`?`	`sharedbytes.Region`
`?`	`integer`
`?`	`integer`

Returns

Type	Description
`sharedbytes.Region`

Raises

when the bounds fall outside the region

`view`#

view: function(borrows self: sharedbytes.Region, integer?, integer?): span.ByteSpan borrows (self)

A read-only borrowed view over the selected bytes, whole by default.

Arguments

Name	Type	Description
`borrows self`	`sharedbytes.Region`
`?`	`integer?`
`?`	`integer?`

Returns

Type	Description
`span.ByteSpan borrows (self)`

Raises

when the bounds fall outside the region

`viewAs`#

viewAs: function<T>(borrows self: sharedbytes.Region, ctype<T>): span.Span<T> borrows (self)

A checked zero-copy view of the complete region as physical elements.

Arguments

Name	Type	Description
`borrows self`	`sharedbytes.Region`
`?`	`ctype<T>`

Returns

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

Raises

when the region is not aligned or is not a whole number of elements

`text`#

text: nosuspend function(sharedbytes.Region): string

The region's bytes copied and interned as an ordinary string.

Arguments

Name	Type	Description
`?`	`sharedbytes.Region`

Returns

Type	Description
`string`

Raises

when the region's engine storage has been released

Functions#

`sharedbytes.builder`function#

function sharedbytes.builder(): affine(sharedbytes.Builder)

Opens an empty builder.

Returns

Type	Description
`affine(sharedbytes.Builder)`

Raises

when the engine cannot allocate the builder

`sharedbytes.copy`function#

function sharedbytes.copy(text: string): sharedbytes.Region

Copies text once into an engine-owned region.

Arguments

Name	Type	Description
`text`	`string`

Returns

Type	Description
`sharedbytes.Region`

Raises

when the engine cannot allocate the region

`sharedbytes.readFile`function#

function sharedbytes.readFile(path: string): sharedbytes.Region

Reads a whole file directly into an engine-owned region, with no intermediate Lua string for the payload.

Arguments

Name	Type	Description
`path`	`string`

Returns

Type	Description
`sharedbytes.Region`

Raises

when the file cannot be opened, sized, or read

nupp.mem.sharedbytes

Module contents

Types

Functions

Types#

Builderrecord#

Methods

append#

Arguments

Returns

Raises

reserve#

Arguments

Returns

Raises

commit#

Arguments

Returns

Raises

freeze#

Arguments

Returns

Raises

drop#

Arguments

Returns

BuilderTokeninterface#

Methods

drop#

Arguments

Returns

Regionrecord#

Methods

size#

Arguments

Returns

slice#

Arguments

Returns

Raises

view#

Arguments

Returns

Raises

viewAs#

Arguments

Returns

Raises

text#

Arguments

Returns

Raises

Functions#

sharedbytes.builderfunction#

Returns

Raises

sharedbytes.copyfunction#

Arguments

Returns

Raises

sharedbytes.readFilefunction#

Arguments

Returns

Raises

`nupp.mem.sharedbytes`

`Builder`record#

`append`#

`reserve`#

`commit`#

`freeze`#

`drop`#

`BuilderToken`interface#

`drop`#

`Region`record#

`size`#

`slice`#

`view`#

`viewAs`#

`text`#

`sharedbytes.builder`function#

`sharedbytes.copy`function#

`sharedbytes.readFile`function#