mailboxModule
Inter-runtime communication mechanism using FIFOs and completions.
This module provides a way for different Lunatik runtimes (Lua states) to send and receive messages to/from each other. It uses a FIFO queue for message storage and a completion object for synchronization.Mailboxes are unidirectional (inbox for receiving only, outbox for sending only). Messages are serialized as strings.
The receiver creates the inbox and hands its queue and event to the other runtime, as
through runtime:resume, where the sender builds mailbox.outbox(queue, event): a mailbox
built on an existing fifo needs its completion too. send works in any context; receive
sleeps, and a softirq or hardirq runtime refuses it.
See also
Usage
-- receiver.lua, run with `lunatik run receiver`
local lunatik = require("lunatik")
local mailbox = require("mailbox")
local inbox = mailbox.inbox(4096)
local sender <close> = lunatik.runtime("sender")
sender:resume(inbox.queue, inbox.event)
print(inbox:receive(1000)) -- hello 5
-- sender.lua
local mailbox = require("mailbox")
local function send(queue, event)
mailbox.outbox(queue, event):send("hello")
end
return send
Class MailBox
| MailBox:receive ([timeout]) | Receives a message from the mailbox. |
| MailBox:send (message) | Sends a message to the mailbox. |
mailbox
| inbox (q, e) | Creates a new inbox (receive-only mailbox). |
| outbox (q, e) | Creates a new outbox (send-only mailbox). |
Class MailBox in detail
Metatable for MailBox objects.
This table defines the methods available on mailbox instances.
- MailBox:receive ([timeout])
-
Receives a message from the mailbox.
This function will block until a message is available or the timeout expires.
Not available on outboxes.
Parameters
- timeout
number
maximum time to wait in milliseconds, from 0 to
231 - 1. If omitted or nil, waits indefinitely. If 0, returns immediately. (optional)
Returns
-
string or nil
the message, or
nilif the wait elapsed, timeout 0 on an empty mailbox included, or the event fired with the queue empty. - integer the message’s length, beside a message.
Raises
“send-only mailbox” on an outbox; “out of bounds” for a timeout outside its range;ERESTARTSYSwhen a signal orthread:stop()interrupts the wait; “malformed message” on a truncated header; “runtime context mismatch” from a softirq or hardirq runtime. - timeout
number
maximum time to wait in milliseconds, from 0 to
- MailBox:send (message)
-
Sends a message to the mailbox.
Not available on inboxes.
Parameters
- message string message to send.
Returns
-
boolean
trueif the message was queued,falseif the queue has no room for it.Raises
“receive-only mailbox” on an inbox; “out of bounds” for a message whose length plus asize_texceeds the queue’s capacity.
mailbox in detail
- inbox (q, e)
-
Creates a new inbox (receive-only mailbox).
Parameters
- q
(fifo|number) Either an existing FIFO object or a capacity for a new FIFO, at least
string.packsize("T")bytes:receive()pops a header of that size. - e
(completion) [optional] An existing completion object. If nil and
qis a number, a new completion object will be created.
Returns
-
(MailBox) A new inbox object.
Usage
local my_inbox = mailbox.inbox(4096) -- 4096 bytes; a message takes its length plus a size_t local msg = my_inbox:receive()
- q
(fifo|number) Either an existing FIFO object or a capacity for a new FIFO, at least
- outbox (q, e)
-
Creates a new outbox (send-only mailbox).
Parameters
- q
(fifo|number) Either an existing FIFO object or a capacity for a new FIFO, at least
string.packsize("T")bytes:receive()pops a header of that size. - e
(completion) [optional] An existing completion object. If nil and
qis a number, a new completion object will be created.
Returns
-
(MailBox) A new outbox object.
Usage
local my_outbox = mailbox.outbox(4096) -- 4096 bytes; a message takes its length plus a size_t my_outbox:send("hello")
- q
(fifo|number) Either an existing FIFO object or a capacity for a new FIFO, at least