Task
Tasks run functions at the same time. See the tour page Tasks.
Tasks are cooperative: a task yields when it waits for I/O, a timer, a channel or another task, and at the end of each turn. They run on the VM’s schedulers, one per logical core unless --schedulers N sets the count, so tasks may run in parallel and the order of output between tasks is not fixed. With --schedulers 1 one task runs at a time: I/O concurrency without CPU parallelism, in the order of a single run queue. Each task has its own scopes, call depth and return handling. Tasks inherit ports, arguments and builtin services, and all share the --max-steps counter. Shared streams have no ordering guarantee across tasks. Task is a reserved name, and a task has no constructor, equality, fields, indexing or JSON encoding.
Task.spawn #
Task.spawn(function: Fn[R]) -> Task[R]
Task.spawn(function: Fn[A, R], argument: A) -> Task[R]Starts function(argument) in a new task and returns its Task handle. Without an argument, the function takes no parameter: Task.spawn(&work) starts work(). The function takes one parameter at most; use a struct for several values.
A block is the function too: Task.spawn do ... end runs the block as a task, like Ruby’s Thread.new { }, and it may capture locals. Give a block or a function reference, not both (CHECK-BLOCK-TARGET). Task.spawn_owning always takes the handle.
- A file, socket, listener, process or server belongs to the task that opened it and closes when that task ends (returns, crashes or is cancelled). So open a long-lived handle in the task that keeps it, not in a helper: nothing is given to the parent, and a handle opened in a helper and returned through
Task.awaitis closed when the helper ends. - A regular file is closed with its output written before
Task.awaitof the ended task returns, so what a helper wrote to a regular file is on disk when the parent’s await returns. The await does not wait for a flush to a FIFO or a pipe. - Ownership decides who closes a handle, not who may use it: any task that holds the handle can use it until its owner closes it.
Task.spawnmoves nothing: a handle in the argument, or in a struct or list in it, stays with the caller. To give it away, useTask.spawn_owning, which also takes such a struct or list.
def greet(name: String) -> String = "hi #{name}"
def main() -> Void
task = Task.spawn(&greet, "Ana")
puts(Task.await(task))
endhi AnaTask.spawn_owning #
Task.spawn_owning(function: Fn[A, R], handle: A) -> Task[R]Starts function(handle) like Task.spawn and gives handle to the new task in the same call.
- The argument must be a
File.Handle,TCP.Socket,TCP.Listener,Process,HTTP.Server,Channel[T], aC.Pointeror a native resource or owned buffer, or a struct, enum,List,MaporResultwhose type holds one (through fields, variant payloads and type arguments). Anything else (anInt, a struct with no handle, anHTTP.Client) isCHECK-NOT-A-HANDLE. A crash or an end never closes anHTTP.Client. - A value that holds handles hands over every one of them: the new task gets the value and closes them all when it ends. An enum variant with no handle hands over nothing. A channel’s
Addressis data, not a handle: put the address of a channel that other tasks keep using in the value, and it stays open (one handle owned, one channel shared). - The caller must own each handle, and can still use it while the new task runs. Otherwise (not owned, already handed over, closed) the caller stops with
RUNTIME-HANDLE-NOT-OWNED, no task is made and no handle moves: all of them or none. Of theC.Pointervalues only an owned buffer (Native.memory_pointer) can be handed over; a pointer that C gave, or a view of a buffer (Native.offset), isRUNTIME-HANDLE-NOT-OWNED. - A server loop can give each accepted connection to its own task, so a crash closes only that connection. A handed-over server takes its listener along and keeps serving after its creator ends.
- A Channel has no opener, so any task can make the first hand-off. The ownership rules are in a producer that owns the channel.
def echo(socket: TCP.Socket) -> Result[String]
line = try TCP.read_line(socket, 2000)
try TCP.send(socket, "echo: #{line}\n", 2000)
ok(line)
end
def main() -> Void
listener = TCP.listen("127.0.0.1", 0).unwrap!
client = TCP.connect("127.0.0.1", TCP.local_port(listener), 2000).unwrap!
connection = TCP.accept(listener, 2000).unwrap!
worker = Task.spawn_owning(&echo, connection)
_ = TCP.send(client, "hello\n", 2000)
puts(TCP.read_line(client, 2000))
puts(Task.await(worker))
puts(TCP.read_line(client, 2000))
TCP.close(client)
TCP.close_listener(listener)
endok("echo: hello")
ok("hello")
error("network: end of input", kind: "net.eof")echo never closes the connection. Its end does, so the client reads the end of the input.
Task.await #
Task.await(task: Task[R]) -> RWaits for the task and gives its result. Waiting again gives the same value, and false, nil and error are normal results.
- A runtime error in a task other than
mainis a crash. It ends only that task: the error goes to stderr at once, within a taskafter the code (--jsonadds"task": true), the task’s own running tasks are cancelled and its handles close. This is sound because values are immutable: a crashed task cannot leave a shared value half-updated, and the only mutable state lives in handles. - Awaiting a crashed task that returns a
Resultgives an error of kindtask.crashedwith the message"task crashed: CODE at FILE:LINE:COLUMN: MESSAGE". For any other type the waiting task stops withRUNTIME-TASK-CRASHED. - A crash that no await sees makes the run exit with code 1 when
mainreturns. - Awaiting yourself, directly or through other tasks (a handle can arrive over a Channel, or inside a closure that captures it), stops with
RUNTIME-TASK-AWAIT-CYCLE.
def parse(text: String) -> Result[Int] = ok(100 / text.to_i!)
def main() -> Void
task = Task.spawn(&parse, "0")
case Task.await(task)
ok(n) -> puts(n)
error(e) -> puts(e.message.start_with?("task crashed: RUNTIME-DIVISION-BY-ZERO"))
end
puts("still running")
endtrue
still runningTask.await with a timeout #
Task.await(task: Task[R], timeout_ms: Int) -> Await[R]Waits at most timeout_ms milliseconds.
Await[R]is a builtin enum:Await.Done(value)holds the result,Await.TimedOut(no payload, no parentheses) means time ran out first.- A
casemust match both variants, or use_.Awaitis reserved (no struct, enum or import alias may use it), andtrydoes not apply to it. - The result can be annotated (
outcome: Await[Int]), printed and interpolated:IO.inspectshowsAwait.Done(42)orAwait.TimedOut.tryon it isCHECK-TYPE-MISMATCHat the call. timeout_msmust be above 0, otherwiseRUNTIME-INVALID-DURATIONat the argument. Call it once with the total time you can spare; do not poll.- A timeout does not cancel the task. It keeps running, and a later await gives its result. An ended task never times out.
- If the task crashes or is cancelled first, you get the plain await’s outcome:
Await.Done(error(text))for aResulttask, otherwiseRUNTIME-TASK-CRASHEDorRUNTIME-TASK-CANCELLED. A crash afterAwait.TimedOutdoes not reach the caller. - A timed await skips the cycle check: a task awaiting itself with a timeout gets
Await.TimedOut, and a plain await of a task that waits with a timeout is notRUNTIME-TASK-AWAIT-CYCLE.
The worker waits on a Channel. The first wait runs out of time, the worker keeps waiting, and the second wait gets its result:
def double(inbox: Channel[Int]) -> Int
n = inbox.recv(10000).unwrap!
n * 2
end
def main() -> Void
inbox: Channel[Int] = Channel.new(1)
task = Task.spawn(&double, inbox)
case Task.await(task, 20)
Await.Done(n) -> puts("done #{n}")
Await.TimedOut -> puts("still working")
end
_ = inbox.send(21, 1000)
case Task.await(task, 10000)
Await.Done(n) -> puts("done #{n}")
Await.TimedOut -> puts("gave up")
end
endstill working
done 42For a Result task, Await.Done holds the Result: match it in a second case.
def parse(text: String) -> Result[Int] = ok(100 / text.to_i!)
def main() -> Void
task = Task.spawn(&parse, "4")
case Task.await(task, 1000)
Await.Done(result) ->
case result
ok(n) -> puts("parsed #{n}")
error(e) -> puts(e)
end
Await.TimedOut -> puts("timed out")
end
IO.inspect(Task.await(task, 1))
endparsed 25
Await.Done(ok(25))A Void task gives Await[Void]: match its payload with _ (Await.Done(_)). A name there is CHECK-VOID-TYPE.
Task.map #
Task.map(items: List[A], limit: Int, timeout_ms: Int, block: Fn[A, Result[R]]) -> List[Result[R]]Runs the function for each item in its own task, at most limit at a time. It gives one Result per item, in the order of items.
- It is never a method:
xs.mapstays the sequentialList.map. - The function is usually the trailing block. It gives a
Result[R](tryworks in it; end a block that cannot fail withok(x)). Any other last value isCHECK-TYPE-MISMATCH.
def slow_double(n: Int) -> Result[Int]
Task.sleep(100)
ok(n * 2)
end
def main() -> Void
results = Task.map([1, 2, 3, 4], 2, 1000) do |n| slow_double(n) end
puts(results)
end[ok(2), ok(4), ok(6), ok(8)]About 200 ms, not 400: a sliding window of two, not batches. Items start in input order.
- An item’s
error(...)does not stop the others. A runtime error (RUNTIME-DIVISION-BY-ZERO) crashes only that item: its slot is an error of kindtask.crashed("task crashed: ..."), the crash counts as observed, and the others go on. An item cancelled on its own (through itsTask.current) giveserror("task: cancelled", kind: "task.cancelled")at once. - The call waits for every item, and the items are children of the caller. To use results as they come, send them over a Channel.
- An empty list needs a type like any empty list (
CHECK-EMPTY-LIST-TYPE). The effect isconcurrency, likeTask.spawn.
def main() -> Void
results = Task.map(["30", "x", "10"], 3, 1000) do |text|
n = try text.to_i
Task.sleep(40 - n)
ok(n * 2)
end
for result in results
case result
ok(n) -> puts("value #{n}")
error(message) -> puts("failed: #{message}")
end
end
endvalue 60
failed: cannot convert "x" to Int
value 20R comes from the expected type of the call, else from the first ok(...) the block gives. If the block gives only error(...), the checker says CHECK-RESULT-TYPE: annotate the variable (results: List[Result[Int]] = Task.map(...)). A function value works too: Task.map(ids, 8, 5000, &fetch).
timeout_ms is per item, from the start of its task to its end, including time spent waiting to run. A slow item is cancelled and its slot is error("task: timed out", kind: "task.timeout"); a block that returns that same error itself looks the same. An item that ends after its deadline but before the caller looks at the clock keeps its result. There is no total timeout: a call takes at most about ceil(items / limit) * timeout_ms.
def fetch(n: Int) -> Result[String]
if n == 2
Task.sleep(10000)
end
ok("page #{n}")
end
def main() -> Void
pages = Task.map([1, 2, 3], 3, 200, &fetch)
puts(pages)
end[ok("page 1"), error("task: timed out", kind: "task.timeout"), ok("page 3")]Limits, checked before any item starts (also for an empty list, which gives []):
limitis 1 to 1024, otherwiseRUNTIME-INVALID-COUNT. Alimitabove the list size starts every item at once.timeout_msabove 0, otherwiseRUNTIME-INVALID-DURATION.
Cancellation (a timed-out item):
- It runs no more code, nor do the tasks it started (even a grandchild whose parent already ended, since a task that ends hands its running children to its parent). Its handles close. An item counts as ended only after the regular files it opened are written and closed, so a file an item wrote is on disk, and its lock released, when the call returns. A timed-out item is the exception: its slot settles at the deadline, and the call does not wait for its files, which close a little later.
- A
Task.mapthat the item called stops: no pending item starts and the items in flight are cancelled. - I/O in progress finishes or times out on its own and its result is dropped. It never closes a handle other items share. A
TCP.acceptor socket read that has taken nothing yet is dropped at once, so the next connection or the later bytes go to the next call. A timed-outHTTP.getconnection closes and does not go back to the pool. - Awaiting a task cancelled with the item stops with
RUNTIME-TASK-CANCELLED, or giveserror("task: cancelled")for aResulttask.
Tips:
limitis mostly for I/O. CPU work runs on at most one item per scheduler at a time, and alimitabove the number of schedulers makes timeouts likelier.- Open handles inside the item. A handle shared by items makes them run in turn (its lock). Many tasks needing one handle: give it to one owner task and talk to it over a Channel.
- Items, captured variables and results are immutable and shared without copies. An item may call
Task.map; the limits multiply. - Starting an item costs one
--max-stepsstep, plus the block’s own, so a call where no item times out has a fixed step count. The caller spends no steps while it waits, and building the result list costs one unit of turn budget per item. With--seed, each item gets its own random generator, split in input order, so the same numbers come whatever order the items end in.
Task.sleep #
Task.sleep(milliseconds: Int) -> VoidPauses the current task. 0 lets other tasks run; a negative value is RUNTIME-INVALID-DURATION.
def late(label: String) -> String
Task.sleep(30)
puts(label)
label
end
def main() -> Void
task = Task.spawn(&late, "second")
puts("first")
_done = Task.await(task)
endfirst
secondA block can run in a task too, when you pass it through a function parameter:
def start(f: Fn[Int, Int]) -> Task[Int] = Task.spawn(f, 20)
def main() -> Void
task = start do |n| n + 1 end
puts(Task.await(task))
end21Task.cancel #
Task.cancel(task: Task[R]) -> VoidStops a task you no longer need, and every task it started. It does not wait: the task is marked and the call returns.
- A task is cancelled by
Task.cancel, by a crash of one of its ancestors, by the timeout of itsTask.mapitem and byHTTP.close_server(the handler tasks). It also takes theTaskRefof Task.current.maincannot be cancelled: a cancel of itsTask.currentdoes nothing. A wrong argument type isCHECK-TYPE-MISMATCHat the argument. - A sleep, a channel wait, an await or an I/O wait ends at once; a task busy in a loop on another scheduler stops at the end of its current turn, so it may end as cancelled even though it reached its return.
- A cancel that lands during the turn wins even when the turn returned, so an item a consuming call (
Channel,TCPorProcessreads) already took is lost. To stop a reader without losing an item, give the read a timeout (Process.poll_line, a receive with a timeout) and let the task end on its own. - Its handles close as when any task ends, so a channel it owns (from
Task.spawn_owning) is closed and its receivers geterror("channel: closed"). - Awaiting it gives
error("task: cancelled")for aResulttask, and otherwise stops the program withRUNTIME-TASK-CANCELLED. - Cancelling a task that already ended, or twice, does nothing. Any task that holds the handle may cancel it. A task that cancels itself, or one that started it, stops right after the call.
- A cancel is not a crash: there is no crash report and the exit code does not change.
def keep(inbox: Channel[Int]) -> Result[Int]
total = 0
while true
total += try inbox.recv(60000)
end
ok(total)
end
def main() -> Void
inbox: Channel[Int] = Channel.new(4)
keeper = Task.spawn(&keep, inbox)
_ = inbox.send(5, 1000)
Task.cancel(keeper)
puts(Task.await(keeper))
enderror("task: cancelled", kind: "task.cancelled")Task.monitor #
Task.monitor(task: Task[R], channel: Channel[M], message: Fn[TaskDown, M]) -> VoidWhen task ends for any reason (it returns, crashes or is cancelled), the runtime sends message(TaskDown(...)) into channel once. There is no select, so the channel is usually the caller’s one channel of an enum, with a variant for the notice: Task.monitor(task, inbox) do |down| Msg.Down(down) end.
TaskDownis a builtin record:task_id: Int(thetask.idof the task),reason: TaskExit, then the diagnostic of a crash:code: String(the stable code, such asRUNTIME-DIVISION-BY-ZERO, to match on),message: String, andfile: String,line: Intandcolumn: Intwhere the error was raised. ForTaskExit.OkandTaskExit.Cancelledthe strings are""and the numbers0.TaskExitis a builtin enum:TaskExit.Ok,TaskExit.CrashedorTaskExit.Cancelled, read asTask.awaitreads the end (a crash first, then a cancel). Both names are reserved.- A task that has ended already gets its notice at once, and a task may have several monitors, each with its own notice. A monitor cannot be removed.
- The send never waits and never fails. A notice that finds the channel full goes in past its capacity, after the values already in it, so it is never lost while the channel is open: a
sendstill finds the channel full until the receiver has taken the values over the capacity. The capacity does not bound these notices: each one waiting past it holds one more value in memory. A notice for a closed channel, or for the channel of System.subscribe, is dropped without an error. - A crash whose notice goes into the channel counts as observed, like an await of it, so it does not make the run exit 1. It counts once the notice is in the channel, even if nobody ever receives it. A monitor through a
TaskRefdoes not observe the crash: only the holder of theTask[R], which can await it, does. taskmay also be theTaskRefof Task.current.- The notice comes as soon as the ended task has closed what it owns, as for
Task.await. Themessageblock runs in a task of its own, outside the caller’s tree, so a cancel never reaches it; keep it to building the message. A runtime error inmessageis a crash of that task, and the notice is lost.
A coordinator that restarts a worker that crashed:
struct Job
id: Int
attempt: Int
end
enum Msg
Done(Int, Int)
Down(TaskDown)
end
def work(job: Job, inbox: Channel[Msg]) -> Void
if job.attempt == 1 and job.id == 2
puts("never #{10 / (job.id - 2)}")
end
_ = inbox.send(Msg.Done(job.id, job.id * 10), 1000)
end
def start(job: Job, inbox: Channel[Msg], running: Map[Int, Job]) -> Map[Int, Job]
task = Task.spawn do work(job, inbox) end
Task.monitor(task, inbox) do |down| Msg.Down(down) end
running.put(task.id, job)
end
def main() -> Void
inbox: Channel[Msg] = Channel.new(16)
running: Map[Int, Job] = {}
for id in 1..3
running = start(Job(id: id, attempt: 1), inbox, running)
end
results: List[String] = []
while running.size > 0
case inbox.recv(5000).unwrap!
Msg.Done(id, value) -> results = results.push("job #{id}: #{value}")
Msg.Down(down) ->
job = running[down.task_id]
running = running.delete(down.task_id)
if down.reason == TaskExit.Crashed
puts("restart job #{job.id} after #{down.code}")
running = start(job.with(attempt: job.attempt + 1), inbox, running)
end
end
end
puts(results.sort)
endrestart job 2 after RUNTIME-DIVISION-BY-ZERO
["job 1: 10", "job 2: 20", "job 3: 30"]The crash of the first attempt still goes to stderr when it happens.
Task.current #
Task.current() -> TaskRef
task.id() -> IntTask.current gives the running task as a TaskRef, so that another task can monitor it. TaskRef is a builtin type, reserved, for a task whose result type is not known where the call is: Task.monitor, Task.cancel and id take it, and an await of it is CHECK-TYPE-MISMATCH at the argument (it has no result to give; monitor it to learn when it ends). It prints as <Task> and has no equality. task.id gives the number that identifies a task in the run, for a Task[R] or a TaskRef: the task_id of its TaskDown.
A child monitors the task that started it:
def watch(parent: TaskRef, report: Channel[String]) -> Void
downs: Channel[TaskDown] = Channel.new(1)
Task.monitor(parent, downs) do |down| down end
down = downs.recv(5000).unwrap!
_ = report.send("parent ended: #{down.reason}", 1000)
end
def parent(report: Channel[String]) -> Int
me = Task.current
_child = Task.spawn do watch(me, report) end
7
end
def main() -> Void
report: Channel[String] = Channel.new(1)
task = Task.spawn(&parent, report)
puts(Task.await(task))
puts(report.recv(5000).unwrap!)
end7
parent ended: TaskExit.OkTask.pending_count #
Task.pending_count() -> IntGives how many tasks have not ended yet, not counting main.
- Waiting, sleeping and awaiting tasks count, and so does the asker unless it is
main. Returned or crashed tasks do not, awaited or not. - The tasks
std/httpstarts for anHTTP.Clientnever count, andTest.testdoes not see them as leftovers.
def wait_for(task: Task[Int]) -> Int = Task.await(task)
def nap(ms: Int) -> Int
Task.sleep(ms)
ms
end
def main() -> Void
puts(Task.pending_count())
first = Task.spawn(&nap, 20)
second = Task.spawn(&wait_for, first)
puts(Task.pending_count())
puts(Task.await(second))
puts(Task.pending_count())
end0
2
20
0Task.unobserved_crash #
Task.unobserved_crash() -> Result[String]Gives ok(text) with the first crash that no Task.await has seen, else error("no unobserved crash"). Asking does not count as seeing.
def boom(n: Int) -> Int = 10 / n
def main() -> Void
puts(Task.unobserved_crash().ok?)
_task = Task.spawn(&boom, 0)
while !Task.unobserved_crash().ok?
Task.sleep(1)
end
puts(Task.unobserved_crash().ok?)
System.exit(0)
endfalse
trueHow a run ends #
Some errors end the whole run, whichever task raises them: a runtime error in main, RUNTIME-STEP-LIMIT, an internal VM error, and System.exit in any task. The first of these wins.
A crash is observed when an await returns its error or halts, when the notice of its monitor through a Task[R] goes into the channel, or when Test.run reports it. If main returns with a crash never observed, the run exits 1 and prints one line on stderr: 2 task crashes were not observed; first: task crashed: ... (with --json, {"unobserved_crashes":2,"first":"task crashed: ..."}).
Returning from main ends the run, and pending tasks never run again. At the end of any run the VM flushes and closes open files and waits for the buffered output of stdout and stderr to reach the pipe or file (bounded by the flush limit, 30 seconds by default, --flush-timeout), frees what native code still owns within the same limit, closes sockets and listeners, and stops and reaps the child processes it started. Standard streams stay open.