Reference · Channels

channel.send

channel.send(str, map | str, any, map | null=) -> bool

What it does

Sends a value to one page in a channel: the channel's name, the peer (the map the channel's function gets, or its id), the value, and options. It gives whether the page was there to take it. The value goes as JSON, up to 1 MiB; { reliable: true } makes sure it arrives in order (over a stream rather than a datagram), and closes a page's connection that cannot keep up rather than drop it. It waits for nothing and needs the net effect. It reaches only a page in a room the code reaches (since 0.7): code run for a page or a request, its tenant's room; a job, a tick and the top level, every tenant's.

Examples

channel.on("game", (msg, peer) => {    if msg.kind == "hello" {        channel.send("game", peer, { you: peer.id, board: board() }, { reliable: true })    }})

With no page in the channel, the answer is false:

print(channel.send("game", "0123456789ab", { pos: [1, 2] }))print(channel.send("game", { id: "0123456789ab", session: {} }, "hi", { reliable: true }))

falsefalse

Edge cases

• A peer that has gone, or that is in another channel, gives false; nothing is kept for a page that is away.
• A peer in another tenant's room gives false too, even by its id: one tenant's handler cannot write to another tenant's page.
• A page that is being let in (its join said yes but the yes has not reached it) gets the message right after its yes.
• The value may be null, text, a number, a map or a list; bytes go as a list of numbers. An error value reaches the page as an error value; one Quillo made (a builtin's) reaches it as err("internal error") in production, and whole under --watch.
• Over a WebSocket, a page that keeps up gets every message, in order. Over 4096 messages waiting for one page, a plain message is dropped and counted; a reliable one closes the connection, so the page comes back and joins again.
• except is an option of channel.broadcast, not of channel.send.

print(channel.send("game", "0123456789ab", null))print(channel.send("game", "0123456789ab", [1, 2, 3]))print(channel.send("room:1.a-b_c", "0123456789ab", "text"))

falsefalsefalse

Errors

A bad channel name, a peer that is neither a peer map nor a hex id, an option that does not exist, and a message over 1 MiB as JSON are runtime errors. A page that is not there is not an error: the result is false.

print(channel.send("game", 42, "hi"))

line 1: `channel.send` takes a peer (as the channel's function gets it, or its id) second

print(channel.send("game", "0123456789ab", "hi", { except: "0123456789ab" }))

line 1: `channel.send` has no option `except`

Chaining

The name comes first, so a pipeline passes it; the bool answers whether to try another way.

channel.on("orders", (msg, peer) => {    if !channel.send("orders", peer, { accepted: msg.id }) {        db.exec("update orders set notify = 1 where id = ?", msg.id)   // tell them next time    }})

print("game" | channel.send("0123456789ab", "hi"))

false

See also

channel.broadcast, channel.on, channel.peers, channel.open

Edit this page on GitHub · every example's output was made by running it (tools/refcheck.mjs) · questions on Discord or r/quillo