Module: `nupp.workers`

Isolated worker threads.

Each worker owns a fresh LuaJIT state on a native thread. Values cross only as bounded string.buffer messages, so neither Lua heap, module state, globals, closures, userdata, nor cdata are shared.

Worker entry modules run from the same stamped payload as their spawner:

The entry obtains its endpoints independently:

A ready receive returns inline. A wait blocks efficiently in an ordinary program and suspends under an installed handler. Closing is cooperative: it wakes a worker blocked in Self:receive, but source that ignores the closed inbox can keep join and stop waiting indefinitely.

Module contents

Types

Type	Kind	Description
`Exit`	record	How a worker ended.
`Self`	record	The worker-side endpoints.
`Worker`	record	A fresh Lua state running on a native thread.

Functions

Function	Kind	Description
`current`	function	Returns the endpoints installed in the current worker state.
`Self:receive`	method	—
`Self:send`	method	—
`Self:serve`	method	—
`spawn`	function	Starts entry in a fresh LuaJIT state.
`Worker:call`	method	—
`Worker:close`	method	—
`Worker:join`	method	—
`Worker:receive`	method	—
`Worker:send`	method	—
`Worker:stop`	method	—
`Worker:tryReceive`	method	—

Types#

`Exit`record#

How a worker ended.

record workers.Exit
    succeeded: boolean
    status: integer
    error: string?
end

Fields

Name	Type	Description
`succeeded`	`boolean`	True when the entry module returned without an uncaught error.
`status`	`integer`	Zero for a clean return and nonzero for a load or runtime failure.
`error`	`string?`	The worker's load or runtime error, when it failed.

`Self`record#

The worker-side endpoints.

record workers.Self
    inbox: Channel
    outbox: Channel
    receive: function(workers.Self): any?
    send: function(workers.Self, any)
    serve: function(workers.Self, function(any): any)
end

Methods

`receive`

Waits for and returns the next payload. Nil means the inbox closed and drained.

receive: function(workers.Self): any?

Arguments

Name	Type	Description
`?`	`workers.Self`

Returns

Type	Description
`any?`

`send`

Sends an ordinary message to the spawner.

send: function(workers.Self, any)

Arguments

Name	Type	Description
`?`	`workers.Self`
`?`	`any`

`serve`

Answers requests until the inbox closes.

serve: function(workers.Self, function(any): any)

Arguments

Name	Type	Description
`?`	`workers.Self`
`?`	`function(any): any`

Fields

Name	Type	Description
`inbox`	`Channel`
`outbox`	`Channel`

`Worker`record#

A fresh Lua state running on a native thread.

record workers.Worker
    _handle: any
    _inbox: Channel
    _outbox: Channel
    _closed: boolean
    _destroyed: boolean
    _exit: workers.Exit?
    _nextId: integer
    _pendingIds: {[integer]: boolean}
    _replies: {[integer]: Frame}
    _messages: {any}
    _firstMessage: integer
    _lastMessage: integer
    send: function(workers.Worker, any)
    tryReceive: function(workers.Worker): any?
    receive: function(workers.Worker, integer?): any?
    call: function(workers.Worker, any): any
    close: function(workers.Worker)
    join: function(workers.Worker): workers.Exit
    stop: function(workers.Worker): workers.Exit
end

Methods

`send`

Queues a copied value without waiting for capacity.

send: function(workers.Worker, any)

Arguments

Name	Type	Description
`?`	`workers.Worker`
`?`	`any`

`tryReceive`

Takes a ready ordinary message without waiting.

tryReceive: function(workers.Worker): any?

Arguments

Name	Type	Description
`?`	`workers.Worker`

Returns

Type	Description
`any?`

`receive`

Waits for an ordinary message, or up to timeoutMs when supplied.

receive: function(workers.Worker, integer?): any?

Arguments

Name	Type	Description
`?`	`workers.Worker`
`?`	`integer?`

Returns

Type	Description
`any?`

`call`

Sends a request and waits for the matching reply.

call: function(workers.Worker, any): any

Arguments

Name	Type	Description
`?`	`workers.Worker`
`?`	`any`

Returns

Type	Description
`any`

`close`

Closes the worker inbox. Nonblocking and idempotent.

close: function(workers.Worker)

Arguments

Name	Type	Description
`?`	`workers.Worker`

`join`

Waits for the worker thread and records how it ended.

join: function(workers.Worker): workers.Exit

Arguments

Name	Type	Description
`?`	`workers.Worker`

Returns

Type	Description
`workers.Exit`

`stop`

Closes, joins, and releases the worker. Idempotent.

stop: function(workers.Worker): workers.Exit

Arguments

Name	Type	Description
`?`	`workers.Worker`

Returns

Type	Description
`workers.Exit`

Functions#

`workers.current`function#

Returns the endpoints installed in the current worker state.

function workers.current(): workers.Self

Returns

Type	Description
`workers.Self`

Raises

outside a worker state

`workers.Self:receive`method#

function workers.Self:receive(): any?

Returns

Type	Description
`any?`

`workers.Self:send`method#

function workers.Self:send(value: any): nil

Arguments

Name	Type	Description
`value`	`any`

Returns

Type	Description
`nil`

`workers.Self:serve`method#

function workers.Self:serve(handler: function(any): any): nil

Arguments

Name	Type	Description
`handler`	`function(any): any`

Returns

Type	Description
`nil`

`workers.spawn`function#

Starts entry in a fresh LuaJIT state.

function workers.spawn(entry: string): workers.Worker

Arguments

Name	Type	Description
`entry`	`string`

Returns

Type	Description
`workers.Worker`	an owned worker that is stopped on every structured exit

`workers.Worker:call`method#

function workers.Worker:call(value: any): any

Arguments

Name	Type	Description
`value`	`any`

Returns

Type	Description
`any`

`workers.Worker:close`method#

function workers.Worker:close(): nil

Returns

Type	Description
`nil`

`workers.Worker:join`method#

function workers.Worker:join(): workers.Exit

Returns

Type	Description
`workers.Exit`

`workers.Worker:receive`method#

function workers.Worker:receive(timeoutMs: integer?): any?

Arguments

Name	Type	Description
`timeoutMs`	`integer?`

Returns

Type	Description
`any?`

`workers.Worker:send`method#

function workers.Worker:send(value: any): nil

Arguments

Name	Type	Description
`value`	`any`

Returns

Type	Description
`nil`

`workers.Worker:stop`method#

function workers.Worker:stop(): workers.Exit

Returns

Type	Description
`workers.Exit`

`workers.Worker:tryReceive`method#

function workers.Worker:tryReceive(): any?

Returns

Type	Description
`any?`

Module: nupp.workers

Module contents

Types

Functions

Types#

Exitrecord#

Fields

Selfrecord#

Methods

receive

Arguments

Returns

send

Arguments

serve

Arguments

Fields

Workerrecord#

Methods

send

Arguments

tryReceive

Arguments

Returns

receive

Arguments

Returns

call

Arguments

Returns

close

Arguments

join

Arguments

Returns

stop

Arguments

Returns

Functions#

workers.currentfunction#

Returns

Raises

workers.Self:receivemethod#

Returns

workers.Self:sendmethod#

Arguments

Returns

workers.Self:servemethod#

Arguments

Returns

workers.spawnfunction#

Arguments

Returns

workers.Worker:callmethod#

Arguments

Returns

workers.Worker:closemethod#

Returns

workers.Worker:joinmethod#

Returns

workers.Worker:receivemethod#

Arguments

Returns

workers.Worker:sendmethod#

Arguments

Returns

workers.Worker:stopmethod#

Returns

workers.Worker:tryReceivemethod#

Returns

Module: `nupp.workers`

`Exit`record#

`Self`record#

`receive`

`send`

`serve`

`Worker`record#

`send`

`tryReceive`

`receive`

`call`

`close`

`join`

`stop`

`workers.current`function#

`workers.Self:receive`method#

`workers.Self:send`method#

`workers.Self:serve`method#

`workers.spawn`function#

`workers.Worker:call`method#

`workers.Worker:close`method#

`workers.Worker:join`method#

`workers.Worker:receive`method#

`workers.Worker:send`method#

`workers.Worker:stop`method#

`workers.Worker:tryReceive`method#