Channel
A channel is a bounded queue: one task sends values, another receives them. See also Tasks.
Channel[T]holds values of one type, any type a variable can have: a task handle, a socket, a file or another channel is allowed, andChannel[Void]isCHECK-VOID-TYPE.- A channel is a handle: passing it to a function or task shares it.
Channelis a reserved name: a userstruct,enumor import alias namedChannelisCHECK-REDEFINED-NAME. puts,print, interpolation and==on a channel areCHECK-TYPE-MISMATCH,.to_sisCHECK-UNKNOWN-METHOD, and a struct with a channel field isCHECK-NOT-ENCODABLEas JSON.IO.inspectprints<Channel>.send,recv,closeandAddress.sendcarry theconcurrencyeffect;new,closed?,empty?andaddresscarry none.- There is no
select, nofor x in channel, and no unbounded or unbuffered channel. send,recv,close,closed?,empty?andaddressalso work as methods:jobs.send(5, 1000)isChannel.send(jobs, 5, 1000).- A channel’s address is data that names it: a table, a message or a constant table can hold it where the channel itself cannot go.
Channel.new #
Channel.new(capacity: Int) -> Channel[T]Holds capacity values, 1 to 1048576, else RUNTIME-INVALID-COUNT. It is always bounded: a full channel makes the sender wait. It needs an expected type (annotation, parameter, field or return type), else CHECK-EXPECTED-TYPE.
def main() -> Void
jobs = Channel.new(4)
enderror[CHECK-EXPECTED-TYPE]def main() -> Void
jobs: Channel[Int] = Channel.new(4)
puts(jobs.closed?)
endfalseChannel.send #
Channel.send(channel: Channel[T], value: T, timeout_ms: Int) -> Result[Void]Adds the value at the back and gives ok(). When full, the task waits for room, a close or timeout_ms. The value is not added on:
error("channel: closed"), orerror("channel: timed out").
timeout_ms is 0 or more; 0 tries once and never waits. A negative value is RUNTIME-INVALID-DURATION. Nothing waits forever.
def main() -> Void
jobs: Channel[String] = Channel.new(2)
puts(jobs.send("a", 0).ok?)
puts(jobs.send("b", 0).ok?)
puts(jobs.send("c", 0).message)
endtrue
true
channel: timed outChannel.recv #
Channel.recv(channel: Channel[T], timeout_ms: Int) -> Result[T]Takes the oldest value (first in, first out) and gives ok(value). When empty, the task waits for a value, a close or timeout_ms. Waiting tasks are served in the order they started waiting, and so are waiting senders, with no barging: a sent value goes straight to the first waiting receiver. A waiter that leaves before it runs, because it was cancelled or its timeout came first, passes what it was given to the next waiter. A receiver that was given a value returns it even if its deadline passes before it runs. No value is lost or added twice. Errors:
error("channel: closed")once closed and every value was taken, orerror("channel: timed out").
def main() -> Void
jobs: Channel[Int] = Channel.new(4)
_ = jobs.send(10, 0)
_ = jobs.send(20, 0)
puts(jobs.recv(0).unwrap!)
puts(jobs.recv(0).unwrap!)
puts(jobs.recv(0).message)
end10
20
channel: timed outChannel.close #
Channel.close(channel: Channel[T]) -> VoidClosing again does nothing. Waiting senders get the closed error, and so do woken senders that have not run yet. Receivers get the values left, then the closed error.
- The sending side should close on every path, receivers should not. If nobody closes it, a receive loop never ends.
- An owned channel also closes when its owner ends (A producer that owns the channel).
def main() -> Void
jobs: Channel[Int] = Channel.new(4)
_ = jobs.send(1, 0)
jobs.close
puts(jobs.send(2, 0).message)
puts(jobs.recv(0).unwrap!)
puts(jobs.recv(0).message)
endchannel: closed
1
channel: closedChannel.closed? #
Channel.closed?(channel: Channel[T]) -> Booltrue once the channel is closed, even while it still holds values, as Ruby’s Queue#closed?, and it stays true. A producer that is busy between sends (decoding the next token, reading the next piece of a file) reads it to learn that the reader has closed the channel before its next send fails. A receiver asks closed? and empty? to learn that the stream ended.
def main() -> Void
jobs: Channel[Int] = Channel.new(4)
_ = jobs.send(1, 0)
jobs.close
puts(jobs.closed?)
puts(jobs.empty?)
puts(jobs.recv(0).unwrap!)
puts(jobs.empty?)
endtrue
false
1
trueChannel.empty? #
Channel.empty?(channel: Channel[T]) -> Booltrue when no value is left to receive: the buffer is empty and no value is reserved for a woken receiver. Once a channel is closed no value arrives, so closed? and empty? says the stream ended, and it stays true. Ask closed? first: a value and the close can both come between an empty? that is true and a closed? after it. After a recv error, closed? and empty? tells the end of the stream from a timeout.
Channel.address #
Channel.address(channel: Channel[T]) -> Address[T]A send-only reference to the channel, as a pid is in Erlang. The channel stays a handle with one reader; its address is data:
- An ATS value, a
Listitem, aMapvalue, a struct field, an enum payload and a message can hold it, and a constant table of addresses is a registry by name. ==istruefor two addresses of one channel.putsandIO.inspectprint<Address N>, whereNcounts the addresses of the run from 1.- It is not JSON-encodable (
CHECK-NOT-ENCODABLE), not aMapkey orSetelement (CHECK-MAP-KEY-TYPE,CHECK-SET-ELEMENT-TYPE), and not allowed in a constant (CHECK-CONSTANT-TYPE). - It does not keep the channel alive, and it is not a handle:
Task.spawn_owningdoes not hand it over (one handle owned, one channel shared). Addressis not a reserved name: a userstruct Addressis allowed, andAddress[T]with one type argument is always this type, so a generic struct, enum or alias namedAddressisCHECK-REDEFINED-NAME.
Address.send #
Address.send(address: Address[T], value: T, timeout_ms: Int) -> Result[Void]Channel.send to the channel of the address, with the same waits, timeouts and errors: error("channel: closed") once the channel is closed. error("address: gone") once nothing else reaches the channel and the collector has freed it, so no task can receive from it any more. A send from another run is RUNTIME-ADDRESS-CONTEXT. There is no recv on an address.
def main() -> Void
inbox: Channel[Int] = Channel.new(4)
names: ATS[String, Address[Int]] = ATS.new()
names.put("counter", inbox.address)
to = names.get("counter").unwrap!
puts(to == inbox.address)
puts(to.send(7, 1000).ok?)
puts(inbox.recv(0).unwrap!)
inbox.close
puts(to.send(8, 1000).message)
endtrue
true
7
channel: closedA producer and a consumer #
The receive loop: on an error, closed? and empty? says whether the stream ended, else it was a timeout and the loop receives again. The producer closes on every path: send_all holds the trys, so produce always reaches jobs.close.
def send_all(jobs: Channel[Int]) -> Result[Void]
for n in 1..5
try jobs.send(n, 1000)
end
ok()
end
def produce(jobs: Channel[Int]) -> Result[Void]
result = send_all(jobs)
jobs.close
result
end
def main() -> Void
jobs: Channel[Int] = Channel.new(2)
producer = Task.spawn(&produce, jobs)
total = 0
while true
case jobs.recv(1000)
ok(n) -> total += n
error(_) -> break if jobs.closed? and jobs.empty?
end
end
puts(total)
puts(Task.await(producer).ok?)
end15
trueThe same consumer as a Lazy needs no loop: jobs.lazy(1000).reduce(0) do |total, n| total + n end is ok(15).
A producer that owns the channel #
Task.spawn_owning(&produce, jobs) makes the task the owner. When it ends in any way (returns, crashes, cancelled) the channel closes. The receiver gets the values already sent, then the closed error at once, with no timeout wait when the producer died.
def produce(jobs: Channel[Int]) -> Result[Void]
try jobs.send(1, 1000)
try jobs.send(2, 1000)
zero = 0
try jobs.send(100 / zero, 1000)
ok()
end
def main() -> Void
jobs: Channel[Int] = Channel.new(4)
producer = Task.spawn_owning(&produce, jobs)
while true
case jobs.recv(5000)
ok(n) -> puts(n)
error(e) ->
puts(e)
break
end
end
puts(Task.await(producer).ok?)
end1
2
channel: closed
falseOwnership rules:
- A channel never handed over has no owner: only
closecloses it.Task.spawn(&f, jobs)does not make an owner. - The first
Task.spawn_owningcan come from any task. After that only the owner can hand it on; any other task, or any task once it is closed, stops withRUNTIME-HANDLE-NOT-OWNED. Any task can still callChannel.close. - There is one owner. For several producers, use the next pattern.
One handle owned, one channel shared #
Task.spawn_owning hands over every handle in its argument, so a channel in that argument closes when the task ends. To give a task its own handle (a socket, a channel of its own) and also a channel that other tasks keep using, put the shared channel’s address in the argument: an address is data, so the shared channel stays open.
struct Link
jobs: Channel[Int]
results: Address[Int]
end
def serve(link: Link) -> Result[Int]
n = try link.jobs.recv(1000)
try link.results.send(n * 10, 1000)
ok(n)
end
def main() -> Void
results: Channel[Int] = Channel.new(4)
jobs: Channel[Int] = Channel.new(1)
_ = jobs.send(4, 0)
worker = Task.spawn_owning(&serve, Link(jobs: jobs, results: results.address))
puts(Task.await(worker).ok?)
puts(jobs.closed?)
puts(results.closed?)
puts(results.recv(0).unwrap!)
endtrue
true
false
40Several sources #
There is no select. Merge sources into one channel of an enum, one variant per kind of event. A coordinator awaits every source, then closes the channel, so the receive loop ends.
enum Event
Item(String, Int)
Failed(String)
end
struct Source
name: String
count: Int
events: Channel[Event]
end
struct Coordinator
sources: List[Task[Void]]
events: Channel[Event]
end
def emit(source: Source) -> Void
i = 1
while i <= source.count
_ = source.events.send(Event.Item(source.name, i * 10), 1000)
i += 1
end
if source.count == 0
_ = source.events.send(Event.Failed("#{source.name} has nothing"), 1000)
end
end
def coordinate(c: Coordinator) -> Void
c.sources.each do |source| Task.await(source) end
c.events.close
end
def main() -> Void
events: Channel[Event] = Channel.new(2)
sources = [
Task.spawn(&emit, Source(name: "a", count: 3, events: events)),
Task.spawn(&emit, Source(name: "b", count: 0, events: events)),
Task.spawn(&emit, Source(name: "c", count: 2, events: events)),
]
coordinator = Task.spawn(&coordinate, Coordinator(sources: sources, events: events))
totals: Map[String, Int] = {}
while true
case events.recv(1000)
ok(event) ->
case event
Event.Item(name, value) -> totals = totals.put(name, totals.get(name, 0) + value)
Event.Failed(text) -> puts(text)
end
error(_) -> break if events.closed? and events.empty?
end
end
Task.await(coordinator)
totals.keys.sort.each do |name| puts("#{name}: #{totals.get(name, 0)}") end
endb has nothing
a: 60
c: 30State owned by one task #
Tasks share no mutable values except ATS tables, so state that several tasks update with more than one table call belongs to one owner task that receives messages on a channel and keeps the state in its own variables.
def count(inbox: Channel[Int]) -> Int
total = 0
while true
case inbox.recv(1000)
ok(n) -> total += n
error(_) -> break if inbox.closed? and inbox.empty?
end
end
total
end
def send_three(inbox: Channel[Int]) -> Void
_ = inbox.send(1, 1000)
_ = inbox.send(2, 1000)
_ = inbox.send(3, 1000)
end
def main() -> Void
inbox: Channel[Int] = Channel.new(4)
counter = Task.spawn(&count, inbox)
sender = Task.spawn(&send_three, inbox)
Task.await(sender)
inbox.close
puts(Task.await(counter))
end6Waiting on each other #
A task waiting on a channel always holds a timer, so tasks waiting for each other end with timeout errors instead of hanging.
def wait_for(inbox: Channel[Int]) -> Result[Int] = inbox.recv(20)
def main() -> Void
inbox: Channel[Int] = Channel.new(1)
task = Task.spawn(&wait_for, inbox)
puts(Task.await(task).message)
endchannel: timed outA task that receives its own handle over a channel and awaits it stops with RUNTIME-TASK-AWAIT-CYCLE; for a Result task the waiter gets the crash as an error.
def follow(inbox: Channel[Task[Result[Int]]]) -> Result[Int]
me = inbox.recv(1000).unwrap!
Task.await(me)
end
def main() -> Void
inbox: Channel[Task[Result[Int]]] = Channel.new(1)
task = Task.spawn(&follow, inbox)
_ = inbox.send(task, 1000)
puts(Task.await(task).message.start_with?("task crashed: RUNTIME-TASK-AWAIT-CYCLE"))
endtrue