`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.

const sharedbytes = nupp.mem.sharedbytes

const region = sharedbytes.copy("hello, region")
const hello = region:slice(0, 5)
assert(hello:length() == 5 and hello:toString() == "hello")

A region is storage, so its positions are zero-based offsets and counts, as a nupp.io.Buffer's are: slice(offset, count) and view(offset, count) name count bytes starting offset bytes in.

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.newBuilder()
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():toString() == "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 an engine-owned block.

Functions

Function	Kind	Description
`copy`	function	Copies text once into an engine-owned region.
`newBuilder`	function	Opens an empty builder.
`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 ...

A growable engine allocation that becomes a region when frozen.

Members

Name	Kind	Description
`append`	method	Appends the chunk's bytes to the builder's storage.
`reserve`	method	Grows the storage and lends a checked writer over exactly count uninitialized bytes past what is already committed.
`commit`	method	Closes the open reservation, keeping its first written bytes as content; a short read commits what arrived, and the...
`freeze`	method	Consumes the builder and transfers its allocation into a region.
`drop`	method	Releases an unfrozen builder's storage at scope exit.

`append`method#

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

Type	Condition
`string`	when a reservation is open or the engine cannot grow the storage

`reserve`method#

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

Type	Condition
`string`	when count is not a nonnegative integer, a reservation is already open, or the engine cannot grow the storage

`commit`method#

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

Type	Condition
`string`	when `written` is not a nonnegative integer, no reservation is open, or `written` exceeds it

`freeze`method#

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

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

`drop`method#

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#

interface sharedbytes.BuilderToken is nupp.Affine<self.drop> ...

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

Members

Name	Kind	Description
`drop`	method

`drop`method#

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 ...

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

Members

Name	Kind	Description
`length`	method	How many bytes the region holds.
`slice`	method	A zero-copy region over count bytes starting offset bytes into this one.
`view`	method	A read-only borrowed view over count bytes starting offset bytes in, the whole region by default.
`viewAs`	method	A checked zero-copy view of the complete region as physical elements.
`toString`	method	The region's bytes copied and interned as an ordinary string.

`length`method#

length: @nosuspend function(sharedbytes.Region): integer

How many bytes the region holds.

Arguments

Name	Type	Description
`?`	`sharedbytes.Region`

Returns

Type	Description
`integer`

`slice`method#

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

A zero-copy region over count bytes starting offset bytes into this one.

Arguments

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

Returns

Type	Description
`sharedbytes.Region`

Raises

Type	Condition
`string`	when the extent falls outside the region

`view`method#

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

A read-only borrowed view over count bytes starting offset bytes in, the whole region by default.

Arguments

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

Returns

Type	Description
`span.ByteSpan borrows (self)`

Raises

Type	Condition
`string`	when the extent falls outside the region

`viewAs`method#

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

Type	Condition
`string`	when the region is not aligned or is not a whole number of elements

`toString`method#

toString: @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

Type	Condition
`string`	when the region's engine storage has been released

Functions#

`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

Type	Condition
`string`	when the engine cannot allocate the region

`sharedbytes.newBuilder`function#

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

Opens an empty builder.

Returns

Type	Description
`affine(sharedbytes.Builder)`

Raises

Type	Condition
`string`	when the engine cannot allocate the builder

`sharedbytes.readFile`function#

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

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

Arguments

Name	Type	Description
`path`	`string`	the native path of the file to read

Returns

Type	Description
`sharedbytes.Region?`	the region, or nil when the file cannot be opened, sized, or read
`string?`	why it could not be read, when unsuccessful

nupp.mem.sharedbytes

Module contents

Types

Functions

Types#

Builderrecord#

Members

appendmethod#

Arguments

Returns

Raises

reservemethod#

Arguments

Returns

Raises

commitmethod#

Arguments

Returns

Raises

freezemethod#

Arguments

Returns

Raises

dropmethod#

Arguments

Returns

BuilderTokeninterface#

Members

dropmethod#

Arguments

Returns

Regionrecord#

Members

lengthmethod#

Arguments

Returns

slicemethod#

Arguments

Returns

Raises

viewmethod#

Arguments

Returns

Raises

viewAsmethod#

Arguments

Returns

Raises

toStringmethod#

Arguments

Returns

Raises

Functions#

sharedbytes.copyfunction#

Arguments

Returns

Raises

sharedbytes.newBuilderfunction#

Returns

Raises

sharedbytes.readFilefunction#

Arguments

Returns

`nupp.mem.sharedbytes`

`Builder`record#

`append`method#

`reserve`method#

`commit`method#

`freeze`method#

`drop`method#

`BuilderToken`interface#

`drop`method#

`Region`record#

`length`method#

`slice`method#

`view`method#

`viewAs`method#

`toString`method#

`sharedbytes.copy`function#

`sharedbytes.newBuilder`function#

`sharedbytes.readFile`function#