Skip to content
Weaverv0.5.0

Errors and concurrency

Errors are values, with no exceptions. Tasks are structured: a task belongs to the block that launched it, or to the pool that runs it, and none outlives the program. The syntax keeps the simple case short; the levers (pools, context, cancellation, groups) remain within reach.

Result<T, E> is an ordinary sum type: either a value or an error, never both. It is stored, transformed and matched by match like any value. The syntax lightens what surrounds it, without exceptions or hidden control flow.

The operators reuse the type syntax: ? for absence (T?, x?.y), ! for failure (T ! E, x!). ! leaves the function, ? stays within the expression.

Form Equivalent to
fn f(): T ! E fn f(): Result<T, E>
fn f() ! E fn f(): Result<(), E>
fn f(): T ! Result<T, _>: inferred error union, for private functions (see below)
fail e return Err(e)
Value of type T after return, or expression body Ok(value)
End of the body, or a bare return, in a () ! E function Ok(())
x! The value of x, or exit from the function with its error
  • Constructors. Some, None, Ok and Err take their type from the context (annotation, parameter, return type, including through if, match and blocks); Some(x) also infers it from x. The success of a () ! E is written Ok or Ok(()), and matched by Ok, Ok(_) or Ok(()). These four names belong to the prelude: an enum cannot reuse them.
  • ! is the only propagation. x! returns the value of x, or leaves the function with its error. A type that adopts Try<T, E> (core), fn toResult(sink self): T ! E, propagates the same way: x! is x.toResult()!. Every point where an error can rise stays visible. The error must be part of the declared union, or convert into it through From.
  • Error unions. User ! DbError | ParseError composes without a wrapping type. A union is a type whose members have no order and no duplicates (A | B is B | A, A | (A | B) is A | B): a value of a member, or of a union of some members, becomes the union wherever the union is expected, fail NotFound(id), val e: DbError | ParseError = Timeout. A pattern matches a whole member by the name of its type, ParseError(e), or a variant of a member by its name, NotFound(id), qualified when two members use it, DbError.NotFound(id). e.message() and e.location() exist on every union, each member being an Error. A generic can open the union: fn orZero<E>(r: Int ! E | Timeout), called with an Int ! DbError | Timeout, infers E = DbError.
  • Conversion. contract From<E> { fn from(e: E): Self } (core) converts an error: !, fail and returning a T ! E' call from when the function’s error type does not contain E’ but adopts From<E'>, an adoption by the collected error type (section 4).
  • Result passed through as is. An expression already of type T ! E', where E' is included in E, is returned without being wrapped. Ok is written only if T is itself a Result.
  • A Result is not discarded. A statement whose value is a Result and gets lost is an error: its error would be ignored with nothing to show it. It is propagated with !, handled with catch, or deliberately dropped with val _ = f(). This also holds for the last statement of a function or loop body, which does not yield its value.
  • Inferred error. fn load(p: Path): Config ! fails with the union of what its body propagates: the error of each x!, the value of each fail, that of a T ! E returned as is. Only a private function writes it: a public function states its errors. A function that reaches itself, directly or through another whose error is inferred, must write its own; a function that never fails drops its !. A block lambda likewise infers its error, the union of all those it propagates.
  • Context. .context("reading ${path}") chains a message without losing the cause: on a T ! E, it yields a T ! Context<E>, Context<E> = { context: String, cause: E, at: Location }, at being where .context is called, and its message is built only on an error. Its location() is that of the cause, or failing that its own. It handles a Result that carries a resource right away, like !: using f = File.open(p).context("reading ${p}")!. A Context’s message chains them, “reading a.json: file not found”; a catch matches Context(c) like any other member, then c.cause.
  • panic. Reserved for bugs (violated invariant, index out of bounds): panic("impossible state"), a core function visible everywhere, whose type is Never, and which records where it is called, Location.caller(). It unwinds the current task up to the nearest barrier, running its using, defer and errdefer on the way, from the most recent to the oldest, like an exit on error: a resource already given up is not given up a second time, a disposal that fails is dropped, and a panic during this cleanup stops everything without running the rest. An integer overflow, a division by zero (section 2) and an index out of bounds are panics too. Its message gives where it arose, panic: index 5 out of bounds for length 2 (main.wft:5:3), the line and column of the statement, except for a line of core. Without a barrier, the task’s executor decides (below); by default the other tasks stop with the program, without running their cleanups, and the program exits with code 101. In abort mode, [package] panic = "abort" in weaver.toml or weaver build --panic=abort, a panic writes its message and calls abort(): nothing runs any more, neither defer nor disposal, the system keeps a core dump of it, and the code no longer registers the cleanups a panic would run.
  • Catching a panic. Panic.catching(() => body) (core) runs body behind a barrier and returns its value, a T ! Halt: a panic below it, or a Process.exit, unwinds to the barrier, runs the cleanups registered since, and comes back as an error. A program that must not stop, embedded software or a server, catches where it can go on: it restarts a part, or goes into a safe state. It is a function rather than a form of the language.
    match Panic.catching(() => step(state)) {
    Ok(next) => state = next
    Err(Halt.Panicked(message, at)) => state = safeState() // at: where it arose
    Err(Halt.Exited(code)) => shutdown(code)
    }
    • Halt is an enum of core that adopts Error: Panicked(message, at), at being where the panic was called, its location(), or Exited(code). A panic the program does not call, an index out of bounds, an overflow, a division by zero, is located at the operation that failed.
    • A barrier costs a setjmp when it is set, nothing elsewhere: a call that does not catch pays nothing. The unwinding goes through tables the compiler writes, a landing pad per state of a frame’s cleanups, and costs nothing on the normal path.
    • What the abandoned frames held is freed, their arenas left, when a barrier catches the panic: a panic caught in a loop leaks nothing. Without one, the program stops after the using, defer and errdefer, and the system takes the memory back. Locks taken by Mutex.with and the other scoped calls of std are released, through their cleanups.
    • In abort mode, which writes no landing pad, Panic.catching is rejected by the compiler.
  • A panic in a launched task. The executor of the task decides what its panic does, once the task’s cleanups have run: ThreadPool(threads: 8, onPanic: halt => .isolate) receives each Halt and returns a PanicPolicy (weaver.task). .stop, and a pool without onPanic, stop the program as above. .isolate keeps the panic within the task: whoever awaits its promise panics in turn with the same Halt, which a Panic.catching around the await catches, and a detached task’s panic is reported like its errors, to the pool’s onError. Pool.global().onPanic(halt => .isolate) sets the global pool’s, at the start of main, and any pool’s can change while it runs, a task keeping the policy it started with. The function runs on the task’s thread, and may count failures or restart work; halt.raise() passes a caught Halt on, as Process.exit does for Exited.
  • Process.exit(code) unwinds like a panic, running the cleanups, up to the nearest barrier, which receives Exited(code); without one, the program exits with code. Process.exitNow(code) exits at once, without running anything, as exit did.
fn loadUser(id: Uuid): User ! DbError | ParseError {
val row = db.query(sql"SELECT data FROM users WHERE id = ${id}")!
if row.deleted { fail NotFound(id) }
return Json.decode<User>(row.data)!
}

catch. It matches the error by patterns and produces the value.

val user = loadUser(id) catch {
NotFound(_) => User.guest()
Timeout => loadUser(id)! // one more attempt
}! // the other errors rise
val port = parse(s) catch _ => 8080
  1. Exhaustive, catch produces a T.
  2. Partial, it produces a T ! (E minus the handled cases): the final ! propagates the rest, and the compiler checks that it appears in the signature. A member of a union leaves the rest when its values are all handled, itself or each of its variants; a partly handled member stays whole.
  3. Arms can exit through fail, return, !, break or continue.
  4. Short form. catch pattern => expr for a single arm.

Declaring errors. Every error adopts contract Error { fn message(self): String; fn location(self): Location? = None } (core): each member of the E of a T ! E must, which the checker requires. message describes the error for a human; location says where it arose, a Location (module, file, line, column, function) that the compiler writes as a constant. A union adopts the contract when each of its members does, Context<E> when E does.

  • #Error implements the contract for an enum, from the variant tags (5.6). An error is an enum: a record does not adopt Error, core’s UserError and Context<E> aside, and #Error on a record is rejected. The message can quote the named fields of the variant, which the compiler checks; e.message() returns it. Every variant must have its own. #Error also gives each value its position: a hidden field, filled where the variant is built, fail NotFound(id), absent from patterns and from the construction the code writes. A developer never writes a position: #Error is the normal way to declare an error, and an impl Error written by hand on an enum has none.
  • UserError (core) is the error built quickly from a text, UserError.new("empty file"), for a function that does not name its failures: fn load(p: Path): Config ! UserError, as Go’s errors.New. fail "empty file" and Err("empty file") build one, at their position, where a UserError, or a union holding one, is expected; an inferred error, fn load(p: Path): Config !, collects a UserError for a text. String is not an error. Two UserErrors are equal by their text.
  • Context<E> records where .context("…") is called, beside the position of its cause: an error that rises through several contexts keeps the place where it arose, and each context adds its own, a light trace that needs no unwinding.
#Error
enum DbError =
| Timeout `error("timed out")`
| NotFound(id: Uuid) `error("user ${id} not found")`
| Constraint(name: String) `error("constraint ${name} violated")`

Two questions are kept apart. Who answers for a task: the block that holds its promise, or the pool for a detached task. Where and how it runs: on a pool, chosen by the function, by the caller, or failing that Pool.global().

pub pool io = ThreadPool(threads: 32, name: "io")
@threadPool(io)
async fn fetchUser(id: Uuid): User ! NetError { … }
async fn page(id: Uuid): Page ! AppError {
val user = fetchUser(id) // Promise<User>: the task starts
using orders = fetchOrders(id) // both run together
return Page(
await user!,
orders.await!
) // if `await user!` exits, orders is cancelled then awaited
}
  • Launching. Calling an async fn launches a task and yields a Promise<T>: fetchUser(id). await f(x) launches it and awaits it in one go; f(x).await is the same thing as a suffix, which chains: fetchUser(id).await!.name. Since the caller would wait anyway, await f(x) calls f in the current task, without launching one, unless f states its pool (@threadPool). An ordinary computation is launched through a lambda, which captures by value (3.1): spawn(() => part.sortedBy(cmp)).
  • A promise is a resource (7.1). On every path, it is awaited, cancelled (p.cancel()), returned or given up. A forgotten promise is a compile error: linearity is what makes concurrency structured, with no block to write. Error paths count: a promise that a ! would leave behind is bound with using, and its disposal cancels it then awaits it.
  • Resources and tasks. An async fn that receives a resource declares it sink (or using), async fn upload(sink f: File): the launched task answers for it, and the caller gives it up to the task; a resource parameter with neither is rejected at the declaration. It can return a resource, which the promise hands to whoever awaits it; a detached task can too, which its pool disposes of, but d.result(), which would copy it, is rejected. A task val does not carry a resource, shared between the tasks its bind launches; nor does a Shared<T>, read through snapshots; both hold it in a shared object. A thread var carries one, disposed of with its thread, if its disposal cannot fail. An async fn also receives a lazy parameter, which the task evaluates when needed.
  • Fire and forget. detach f(x) yields a Daemon<T>, a weak handle. The task belongs to its pool, which awaits or cancels it at its own disposal; its error goes to the pool’s handler (onError), as text: the error type adopts Show. The handle observes and cancels, d.isDone(), d.result() (a T?), d.cancel(), but is not awaited: awaiting means answering for the task, the role of a promise. It is a shared object (8.3), not a resource: it is copied, and discarded without changing anything for the task; the task and its handles share the result, disposed of with the last of them.
  • Groups. await awaits a Promise<T>, or anything that adopts Awaitable<T> (fn wait(sink self): T). await all(tasks) awaits an array of promises and yields their results in their order; await all(f(x), g(y)) awaits everything, in argument order; promises of different types give the tuple of their results. Each result is returned as is, error included, (Int ! A, String ! B) ! Cancelled: all tasks finish, and the caller handles each failure, the one it will retry for instance; a short circuit is written explicitly, through a TaskScope in .failFast. await any(a, b) awaits together sources of different kinds: promises, receptions (rx.receiving()), deadlines (sleep(d), 8.5), or whatever adopts Selectable<T> (source, the source the runtime waits on; claim, which takes what it offers or returns false if another took it; finish, the result). It yields what the first one finishes, of the union of the sources’ types, and disposes of the others, which cancels a promise. Sources that can fail give the union of their values and that of their errors: a promise of Int ! IoError and a reception of String? give (Int | String?) ! IoError. For a varying number of tasks, TaskScope<T, E> is the underlying machinery: scope.spawn(…), scope.awaitAllOrFail() (the results in launch order, or the first error), scope.awaitAny(), scope.results() (each one, errors included), scope.cancel(), and a policy, .collectAll (default: all finish, the first error in launch order comes out), .failFast (the first error cancels the siblings) or .race (the first success cancels the others): a short circuit is written explicitly. TaskScope is Disposable: its disposal cancels what remains and awaits it, without being able to fail (! Never), and disposes of what those tasks return. Their results can be resources, which awaitAny and awaitAllOrFail return; results(), which would return them in an array of Result, does not accept them. weaver.task also provides Latch, Barrier and Semaphore.
  • Cooperative cancellation. p.cancel(), scope.cancel(), and the disposal of a pool cancel. A task is cancelled if its promise is, or that of a task awaiting it; a detached task, through its handle or through the disposal of its pool. It sees this through Task.current().isCancelled(), or Task.current().checkCancelled()!, which fails with Cancelled, the enum of weaver.task. await is a cancellation point: the awaiting task may have been cancelled in the meantime, and the wait then fails with Cancelled. await p on a Promise<T> is therefore a T ! Cancelled, and on a Promise<T ! E> a T ! E | Cancelled, the flattened union; await f(x)! reads (await f(x))!, the propagation applying to the wait. The wait yields to cancellation at once when it is on several sources or a deadline (await any, sleep); a promise, on the other hand, is awaited to the end. A cancelled detached task does not report its Cancelled to the pool.

Pools. A pool is an executor: it receives tasks, and decides how they run. The Executor contract describes it, fn pool(self): Pool, the pool where the tasks entrusted to it run; weaver.task provides ThreadPool (one system thread per worker), which adopts it as Pool, and on e { … } or spawn(…, on: e) accept any executor. Other implementations, such as a pool of lightweight threads with work stealing or priorities, can be written as libraries. A pool declared in another module is designated by its qualified name, on net.io { … }.

pub pool cpu = ThreadPool(
threads: System.cpuCount(),
name: "cpu",
onThreadStart: t => t.pin(core: t.index)
)
on cpu {
val a = compress(block) // calls that do not state their pool go to cpu
}
  • A pool is declared at module level, pool io = ThreadPool(threads: 32, name: "io", onError: msg => log(msg)), and designated by its symbol: @threadPool(io) is checked at compile time. It is borrowed everywhere, io.pool(), but never given up; pub pool opens it to other modules, which import it like any other name. Without onError, a daemon’s error is written to standard error.
  • A pool is a resource, which leaves nothing behind. Its disposal refuses new tasks, cancels its daemons and waits for them to stop, then stops its threads; an error from a daemon goes to onError, and the disposal itself cannot fail (! Never). Tasks held by a promise are already finished: their promise belongs to a block, which does not outlive the pool. Since cancellation is cooperative, a daemon that never checks for it delays the exit: pool.shutdown(within: 5.seconds()) (weaver.time) bounds the wait, on the task’s clock; at the deadline, all the pool’s tasks are cancelled, awaited up to their next cancellation point, and the call fails with Timeout. Launching a task on a disposed pool stops the program.
  • Pool.global() exists without declaring anything, sized on System.cpuCount(). It returns a Pool, which designates a pool without answering for it, like io.pool(). The program’s pools are created before main; after main, they are disposed of in reverse order of declaration, the global pool last.
  • Where a call runs, from the most specific to the most general: spawn(…, on: p) or scope.spawn(on: p, …) at the call; the function’s @threadPool(p) annotation, which states a need of its own (it blocks on I/O); the caller’s on p { … } block; Pool.global(). The on block applies to the launches written in the block, not to those of the functions it calls: it is read on the page. A lambda in the block is a separate function, which may run elsewhere: a launch written in it states its pool.
  • Lightweight threads. A task has its own stack, allocated by its pool; it can suspend anywhere, without its functions being marked. async therefore does not say that a function suspends, but that a call launches a task; await is written in any function, and also in a lazy argument (6.6). A pool chooses its way: one system thread per task, M:N scheduling, or what it does with a blocking system call. An extern "C" call that assumes a large stack or a fixed thread can be pinned by the pool to a system thread. A stack reserves 8 MiB, of which only the touched pages cost anything; a recursive function checks on entry how much it has left, and calls itself again on a fresh stack when it runs out: a deep recursion, a tree traversal, the disposal of a long chain of resources, do not overflow. A task’s stack chains up to 1 GiB of them: beyond, a recursion without end stops the program, panic: stack overflow, before it takes all the memory. A crash, an invalid address read in unsafe code, writes where it happened, segmentation fault at address … then the functions on the stack, whatever WEAVER_BACKTRACE says, before the program dies of its signal.

Execution context. A task, from the moment a thread picks it up until it returns to the pool, sees its context:

val ctx = Task.current() // id, name, pool, cancellation
print("${ctx.name()} #${ctx.id()} on ${Thread.current().name} of pool ${ctx.pool().name()}")
task val requestId: String = "" // bound for the duration of a call, inherited by the tasks it launches
thread var scratch = Bytes(capacity: 1 << 20) // one per thread, kept from one task to the next
val size = scratch.with(s => s.len())
  • Task.current() designates the running task: its id, its name (that of the launched async fn, spawn, or main), its pool, its cancellation. The handle is copied, and stays valid after the task ends.
  • task val carries what follows a task: a request identifier, a log, a deadline. It is bound for the duration of a call, requestId.bind("r-42", () => handle(req)), and passes to the tasks that call launches, detached ones included; a more recent binding shadows the previous one. Outside any bind, it has the value of its declaration, which is required.
  • thread var is specific to each thread: a buffer or a cache, initialized on its first read on that thread, and kept from one task to the next. It is read through scratch.with(s => …), which receives the thread’s value as mut: since a task can change thread at each wait, it stays on its own for the duration of the call, and does not wait there (await is rejected in it; a deeper wait blocks the thread instead of leaving it). What enters the lambda, its captures, and what leaves it, its result, is marked shared (8.3).
  • Thread.current() gives the thread itself: its id, its name (io-0, or main outside pools), its rank in the pool, and what the pool exposes of it: t.pin(core: n) pins it to a core, a preference the system may refuse. A ThreadPool’s onThreadStart is called by each thread, on itself, at its start.

A value passed to another task is logically moved or copied: as a task argument, as a capture of a launched lambda, through a channel, or as the result of a promise. So there is no implicit mutable sharing, and no Arc<Mutex<…>> to write.

Three kinds of values are shared differently. A value is logically copied; passed to another task, it is marked shared. A resource (7.1) has a single owner, who gives it up or disposes of it. An object shared by design, a channel, a lock, a semaphore, exists to be held by several tasks at once: its safety comes from its internal synchronization, not from an owner.

Need Construct Guarantee
Message stream Channel<T>: Sender<T> and Receiver<T>, shared Ownership transfer on each send
Simple shared state val cache = Shared(Map<K, V>()) Read by snapshot, cache.read(c => …), which never waits; write one writer at a time, cache.write(c => …)
State with behavior actor Counter = { … } Methods run one at a time; external calls asynchronous
import weaver.collections.Map
import weaver.task.Shared
val hits = Shared(Map<String, Int>())
fn record(path: String) = hits.write(h => h[path] = (h[path] ?? 0) + 1)

Shared values. A Shared<T> of weaver.task is a shared object, declared at module level, val hits = Shared(Map<String, Int>()), or locally, val words = Shared(String[]()). It does not hold a resource, which reading it would copy.

  • Reading means taking a snapshot. hits.get() returns the current value, hits.read(f) passes it to f. A reader never waits: it keeps the version it received, whatever the others write.
  • Writing, one at a time. hits.write(f) passes f: (mut T) => R its own version of the value, then publishes it, even if f returns an error; the other writers wait. Copy-on-write of values (6.1) does the rest: the writer copies the value’s first block, which readers still hold, and what it puts in it is marked shared. A write therefore costs the size of that first block, a read almost nothing.
  • Atomics. AtomicInt(0) and AtomicBool(false) are modified without a lock, in sequential order: load, store, exchange, compareExchange, and add(n) for an integer, which returns the new value.

Actors. actor Counter = { count: Int, log: String[] } declares a state, which only the methods of impl Counter change, one at a time:

actor Counter = { count: Int }
impl Counter {
fn zero(): Counter = Counter{count: 0}
fn add(mut self, n: Int): Int {
self.count += n
return self.count
}
fn total(self): Int = self.count
}
val c = Counter.zero()
val p = c.add(1) // from outside, a call launches a task and returns its promise
print("${await p!} ${await c.total()!}")
  • A shared object. An actor is a sync type (below): its copies designate the same one, a lambda captures it, a task receives it. Its state lives under a lock: called from outside, a method launches a task that takes the lock, runs, and returns the promise of its result, c.add(1) being a Promise<Int>; inside, self is the state, and self.add(n) calls another method in place, without a task.
  • Generic. actor Cache<K, V> = { … } and impl<K, V> Cache<K, V>: the state has the actor’s parameters, given by the expected type, val c: Cache<String, Int> = Cache.new(), or by the literal’s fields.
  • The state is read only through methods. c.count is rejected outside impl Counter: a method that returns it writes it, fn total(self): Int. A method does not receive a mut parameter, which would not survive the task that runs it; it receives a resource as sink or using, which the launched task passes to it: k.take(conn).await! entrusts the connection to the actor, which keeps it in its state.
  • Contracts and annotations. An actor adopts a contract whose methods are async fn, contract Named { async fn name(self): String }, since called from outside they return a promise: fn f<N: Named>(n: N) = n.name().await receives an actor. It derives nothing, #Show or #Eq would read the state outside its methods; its doc is written with ///.

Objects shared by design. sync type declares a type each of whose values designates a unique object, held by all its copies:

pub sync type Semaphore = { raw: Ptr<Int> }
impl Disposable for Semaphore {
fn dispose(sink self) = unsafe { wv_semaphore_free(self.raw) } // at the last copy
}
  • Copying means sharing. A copy designates the same object; its counter is atomic from creation. A lambda captures it, a task receives it, without giving anything up or marking deeply: spawn(() => sem.acquire()). Passing it as sink gives a copy of it: whoever gives it up keeps it.
  • Its fields do not change. The object changes through its methods, which receive self for reading and synchronize themselves, in unsafe code: only the implementation, in the standard library or a library that answers for it, guarantees that it is safe to share. Ordinary code cannot declare mutable shared state without synchronization.
  • It disappears with its last copy. Its dispose then runs, instead of the scope’s: it cannot fail, and the object is not a resource (7.1). Its counted fields are marked shared at its construction.
  • Channel, Sender, Receiver, Mutex, Semaphore, Latch, Barrier, Shared, AtomicInt, AtomicBool, and Task and Daemon, all from weaver.task, are shared objects.

Locks and synchronization. They belong to tasks, not to system threads: a task can wait while holding a lock, and still holds it if it resumes on another thread. The risk is that of any lock held for long, deadlock.

val hits = Mutex(String[]())
spawn(() => hits.with(h => h.push(path))) // h: mut, the lock held for the duration of the lambda
val pending = hits.with(h => h.len())
val sem = Semaphore(permits: 4) // acquire(), release(), available()
sem.withPermit(() => download(url))
val ready = Latch(count: 3) // countDown(); await ready until zero
val step = Barrier(parties: 4) // arrive() waits for all four, then starts over
  • Mutex<T> guards a value; m.with(f) passes it to f: (mut T) => R with the lock held, and returns what f returns. What enters the lambda, its captures, and what leaves it is marked shared. A task that takes again the lock it holds would wait for itself: the program stops. Likewise if tasks each wait for a lock held by the next, the last one for that of the first: the runtime sees the cycle when it closes, and the program stops with code 101, naming the tasks from the oldest, deadlock: tasks "left", "right" each wait for a lock held by the next.
  • Semaphore(permits: n) counts permits; Latch(count: n) opens at the n-th countDown(), forever, and is awaited with await; Barrier(parties: n) gathers n tasks at each round, and arrive() returns true for the last arrival of the round.

Channels. A channel connects tasks the way a socket connects processes, at memory speed and within the same program.

val (tx, rx) = Channel<Line>(capacity: 64)
val reader = spawn(() => {
for line in lines { tx.send(line)! }
tx.close()
})
for line in rx { handle(line) }
reader.await!
  • Two ends. Channel<T>(capacity: n) yields a Sender<T> and a Receiver<T>, two shared objects: their copies are as many producers and consumers. The channel is closed with tx.close(); the disappearance of the sender’s last copy closes it too, but that is a safety net: a copy that remains in the reader’s scope would keep it open, and its loop would wait. Explicit closing is the rule.
  • Sending gives up. tx.send(v) transfers v: the sender no longer has it, a resource included (tx.send(file)), and v is marked shared. A full channel suspends the sender until a slot frees up: the capacity bounds memory, and slows down whoever produces too fast. A capacity of 0 makes each send a rendezvous. A closed channel, or one whose last receiver has disappeared, refuses the send: send returns () ! ChannelError, Closed, and v is disposed of.
  • Receiving adopts. rx.receive() returns a T?, None once the channel is closed and drained; the message is handed over to the receiver, and is adopted with using if it carries a resource (7.1). A receiver is an iterator: for line in rx, for using msg in rx. Messages that remain when the channel disappears are disposed of with it.
  • Several channels. await any(a.receiving(), b.receiving()) receives from the first one that has a message, or None from the one that is closed and empty; with a deadline, await any(rx.receiving(), sleep(d)) waits at most d, and is Timeout at the deadline.
  • No allocation per message. A channel stores its messages in its ring, at their size: a send copies the value into its slot, a receive takes it back out.

Counting across threads. Values remain counted (6.4). A block touched by two threads is shared: it is marked when a value that reaches it passes to another task, and its counters then become atomic. A block that does not leave its thread, the bulk of them, keeps ordinary counters and pays nothing. Marking traverses the transmitted value once, on the way; a marked block stays marked. A promise’s result is not marked: the task that produced it is finished and keeps nothing of it. A shared counter costs on every update, and more when several threads touch the same one: views and borrowed reads count nothing, which keeps cheap the parallel sort of lines that share the same buffer.

Signature Arguments
fn main() None
fn main(args: String[]) Raw
fn main(args: T) where T: FromArgs Parsed, by T.fromArgs(args). A usage error is shown on standard error and exits with code 2; --help and --version are shown on standard output and exit with code 0

FromArgs is a core contract, which can be adopted by hand: fromArgs(args) builds the value, or exits the program. The official package weft/cli adopts it so that you do not have to write it: import weft.cli.Cli, and #Cli(name: "wc", version: "1.0"), whose generator also writes impl FromArgs; without name:, the program takes the name it was launched under, without its path. Its generator reads the type’s fields: a Bool is a flag; a String, Int, a type that adopts Parse (a #Parse enum, a date, a duration) or their optional is an option that expects a value, read by T.parse, a value that cannot be read being a usage error; a String[] is a repeatable option, or the positional arguments with the cli(positional) tag. A field’s long name is its name in lowercase separated by hyphens (maxLineLength gives --max-line-length), its help is its /// comment, and the tag cli(short: 'c', long: "…", value: "N") specifies the rest. Short flags group (-lc), a value follows its option (-W 7, -W7, --width=7), and -- ends the options. Two flags that contradict each other are settled by order, the last one written winning: binary: Bool `cli(short: 'b', overrides: ["text"])` says that -b clears a -t written before it, and on text the converse; without the converse, the clearing only works in one direction (-t --tag passes, --tag -t keeps both). An overrides that does not name a flag of the type is a compile error. width: Int `cli(default: "8")` gives its value to an absent option, which the help announces, (default: 8); the default of an Int that is not an integer, or a default on an optional, whose absence is None, is a compile error. Without name, a #Cli takes the name of its type in lowercase.

Subcommands are an enum that adopts #Cli: each variant is a command, named after the variant in lowercase separated by hyphens (CommitAll gives commit-all), which carries the #Cli type of its options, or nothing, and whose help is the /// comment. A cli(subcommand) field of the record receives it: the options written before its name go to the record, the rest to the command, and an unknown or missing command is a usage error.

/// A repository manager.
#Cli(name: "vcs")
type Vcs = {
/// Details what is being done
verbose: Bool `cli(short: 'v')`
command: Command `cli(subcommand)`
}
#Cli
enum Command =
/// Adds files to the index
| Add(AddArgs)
/// Shows the state of the tree
| Status

The root’s help lists the commands, vcs add --help describes one of them, and a message names it: vcs add: unknown option "-x". --completion=bash, zsh or fish, at the root, writes the script that completes the command line in that shell: its commands, and the options of the one being typed.

Processes. weaver.process launches programs, looked up in the PATH: Command.new("ls").args(["-l"]).dir("/tmp").env("LANG", "C") composes, then .status()! waits for it to end, .output()! also returns what it writes on its two outputs, read as they come, and .spawn()! returns a Child without waiting for it. Each input or output receives the program’s own, a pipe, or nothing (.stdout(.piped)); a Child gives up its pipes once, takeStdin(), and its disposal closes what remains of them, then waits for it. A Status gives the exit code, or the signal that stopped it; child.kill() sends one, kill by default, .terminate asking it to stop. Process.which(name) finds what Command.new(name) would launch, and Process.id() gives the process’s identifier.

Signals. using watch = Process.signals([.interrupt, .terminate])! catches them: their default action, stopping the program, no longer applies while the watch lives, and watch.next()! waits for the next one without blocking its thread, a cancellation point, so that a server stops cleanly. Disposing of the watch gives them their default action back, once no other watch has them; kill cannot be caught. The runtime’s handler writes the number of each signal to the pipe of each watch, which the waiting task reads.

Networking. weaver.net carries TCP and UDP sockets, over IPv4 and IPv6. TcpListener.bind("0.0.0.0:8080")! listens, port 0 picking a free one that localAddr() reports, and accept()! returns each connection; TcpStream.connect("example.com", 80)! resolves the name and tries each address in turn, TcpStream.connectTo(addr) connects to an address. A connection is a Reader and a Writer, which closes when disposed of; shutdownWrite() signals the end of the stream to the peer. UdpSocket.bind(addr)! sends and receives datagrams, sendTo(data, addr) and receiveFrom(&buf). An address is written SocketAddr or as text, "127.0.0.1:8080", "[::1]:8080"; IpAddr and SocketAddr are read with parse and written as RFC 5952 requires. Net.resolve(host, port) resolves a name with the system resolver. UnixListener.bind(path)! and UnixStream.connect(path)! do the same over a Unix domain socket, named by a path, between processes of one machine under the file system’s permissions; the listener’s disposal removes the path it created. A socket is non-blocking: a read that finds nothing parks the task until the socket is ready, and its system thread runs others, so that a server holds one task per connection, an async fn that receives it as sink. setReadTimeout, setWriteTimeout and setTimeout bound the waits; an expired timeout is TimedOut, and network errors have their kind, connectionRefused, connectionReset, addrInUse, hostNotFound. Waiting on a socket is a cancellation point: the cancelled task leaves it with Interrupted, and a server stops with the task that serves it.

TLS. TlsStream.connect("example.com", 443)! encrypts a TCP connection through the system’s libssl (OpenSSL 3), loaded on first use: the client announces the host and checks that the server’s certificate names it and chains up to a system root. TlsConfig.client(roots: pem) trusts other roots, TlsConfig.server(cert, key) presents a certificate, and TlsStream.client(tcp, host, config) or TlsStream.server(tcp, config) encrypt an established connection. A configuration is a shared object (8.3); a TlsStream is a Reader and a Writer, which waits on its socket like a TCP connection. A rejected certificate, or a failing protocol, is the Tls error.

HTTP. weaver.net.http carries HTTP/1.1, in clear or over HTTPS. Http.get(url)! returns a Response, its status, its headers and its body, whatever its status; Http.post and Http.send(request) send a body, and HttpConnection.open(url) keeps a connection from one request to the next. HttpServer.bind(addr, tls:)! listens, and serve(handler) serves each connection by its own task, each request by handler: (Request) => Response, until the serving task is cancelled. Bodies fit in memory, bounded (setMaxBody), and are read by Content-Length, in chunks, or until close; an invalid request receives 400, one too large 413 or 431. The errors of an exchange are HttpError | IoError.

main can be async: the runtime launches main on the global pool, then waits for it to end and disposes of the pool, which awaits or cancels the detached tasks that remain. It returns (), Exit, or either with ! E. An Err prints prog: message on standard error and exits with code 1. The disposal errors of main’s using rise according to 7.3.

weaver.time separates what Java took twenty years to separate: the machine’s instant, the calendar date, and the time zone that connects one to the other. Each type is an immutable value; none turns into another without it being written.

import weaver.time.{Timestamp, TimeZone, Period, Monotonic, hours, date, time, fmt}
val start = Monotonic.now() // for measuring: does not tell the time
val now = Timestamp.now() // the instant, in UTC
val paris = TimeZone.named("Europe/Paris")!
val meeting = date"2025-03-30".at(time"10:00").in(paris, resolve: .compatible)
val nextWeek = meeting.plus(
Period(days: 7),
resolve: .compatible
) // same wall-clock time, whatever the DST change
val inOneDay = meeting + 24.hours() // exactly 24 hours, perhaps another wall-clock time
print(
"${now} ${meeting} ${start.elapsed()}"
) // 2025-03-28T09:12:44Z 2025-03-30T10:00:00+02:00[Europe/Paris] 3ms
print(meeting.format(fmt"{day:02}/{month:02}/{year} at {hour}h{minute:02}"))
  • Instants. Timestamp is a point on the time line, independent of any time zone: seconds and nanoseconds since 1970-01-01T00:00:00Z, from year -9999 to 9999, Timestamp.min() and Timestamp.max(); a computation that goes outside stops the program, like an integer overflow, and a date likewise. A file’s date, which the system gives as it is written, is brought back within these bounds, Timestamp.clampedUnix(s, nanos:). Time is POSIX time, where every day has 86,400 seconds: leap seconds do not exist. Timestamp.now() reads the clock, t.unixSeconds(), t.subsecNanos(), t.unixMillis() and Timestamp.fromUnix(s, nanos:) go through the Unix epoch; nanoseconds outside one second carry over to the seconds. t + d and t - d move forward or back by a Duration, b - a returns one.
  • Measuring. Monotonic is the reading of a clock that never goes back, untouched by setting the time: Monotonic.now(), m.elapsed(), b - a, which are Durations. It does not tell the time, does not convert to a Timestamp and is not written: only a difference has meaning. Go hides this reading inside its wall time, hence comparisons that depend on where a value came from; here the two are distinct types.
  • Exact durations. Duration is a signed number of nanoseconds, ±292 years: 250.millis(), 5.seconds(), 90.minutes(), 2.hours(), and nanos, micros, free functions of weaver.time that are called as methods through the uniform call (3) and imported like the other names, import weaver.time.{seconds}. It adds, subtracts, multiplies and divides by an integer, with the checked arithmetic of section 2, and adopts Ord; toSeconds(), toMillis() and their kin round it toward zero. "${d}" writes 1h30m0.25s, like Go, 250ms or 1.5µs below one second, and Duration.parse(s) reads it back; d.iso() writes PT1H30M0.25S. There is no days(): a day is not an exact duration, it lasts 23 or 25 hours at a DST change.
  • Civil durations. Period counts in calendar units: Period(years: 1, months: 2, days: 3), Period(weeks: 2) being 14 days, written P1Y2M3D. A Period is added only to a local date or to a date in a time zone; a Duration only to an instant or to a date in a time zone. “In a month” and “in 30 days” are two different computations, and the type says which one is being made.
  • Local dates. LocalDate, LocalTime and LocalDateTime are wall-clock time, with no time zone by choice: a birthday, a shop’s opening hours, an invoice date, which must change for no one. “Local” means “where it is read”, not “in the machine’s time zone”: a local value has none, no operation reads one, and it is never written with an offset. It meets a time zone only through .in(zone), written out, and an instant becomes local only through t.in(zone).dateTime(). A date is read through its methods, d.year(), d.month(), d.day(), d.weekday(), d.dayOfYear(), its fields staying private to the package, which thus keeps the date valid; Month and Weekday are enums (.march, .monday, the week starting on Monday as ISO 8601 requires), m.number() going from 1 to 12. The calendar is the Gregorian calendar of ISO 8601, extended before 1582. A date literal is checked at compile time, date"2024-02-29", time"14:30", datetime"2024-02-29T14:30", by the very code that reads it at run time; at run time, LocalDate.from(year: y, month: m, day: d) returns a LocalDate?, neither an exception nor a silently “corrected” date. d.at(t) makes a LocalDateTime from a date and a time. d.plus(Period(months: 1)) brings a date that does not exist back to the last day of the month (January 31 plus one month gives February 28 or 29); d.plus(p, overflow: .reject) returns None instead. a.until(b) returns the Period between them, a.daysUntil(b) a number of days, d.plusDays(n) moves forward n days.
  • Time zones. TimeZone is a rule of legal time: TimeZone.utc, TimeZone.fixed(hours: 5, minutes: 30), whose parts share one sign, TimeZone.named("Europe/Paris"), which returns TimeZone ! TzError for an unknown name, and TimeZone.local(), that of the place, given by the clock: for the system clock, $TZ (a name, :Europe/Paris, a path, or a POSIX rule such as CET-1CEST,M3.5.0,M10.5.0/3), then the /etc/localtime link, UTC if they say nothing. The tz database comes from the system (/usr/share/zoneinfo, or $TZDIR), up to date with it, read in TZif format and extended by its POSIX rule; weaver build --tzdata, or tzdata = true in the manifest’s [package], embeds it in the executable, about 360 KB, for a minimal container: a time zone the system lacks is then looked up in the executable. z.offsetAt(t), z.abbreviation(t) (CEST) and z.isDst(t) tell its rule at an instant.
  • Instants in a time zone. Zoned is an instant seen in a time zone: t.in(paris), and z.timestamp(), z.dateTime() (a LocalDateTime), z.date(), z.time(), z.offset() (a Duration), z.zone() get back from it. From a wall-clock time to a time zone, the conversion can be ambiguous: at 2:30 on the day of the switch to summer time, the time does not exist; at 2:30 on the day of the switch back, it exists twice. dt.in(zone) therefore returns Zoned ! ResolveError, whose variants Skipped(before, after) and Repeated(earlier, later) carry the candidates, e.pick(r) choosing one of them, and dt.in(zone, resolve: …) chooses in advance: .earlier, .later, or .compatible, the time after the gap and the first of the two. The choice is always written: no rule makes it in place of the program. in(zone) and in(zone, resolve:) are two forms of one method, distinguished by the names of their parameters (3).
  • Computing in a time zone. z + d, d a Duration, moves the instant forward: exactly 24 hours. z.plus(p), p a Period, moves the wall-clock time forward, then places it back in the time zone: the same 10:00 the next day, whether the day has 23 or 25 hours. If the resulting wall-clock time falls into a gap or an overlap, plus also asks for resolve:; without it, it returns Zoned ! ResolveError. Two Zoned are equal if they designate the same instant in the same time zone; they are not ordered, their instants are: a.timestamp() < b.timestamp().
  • Writing and reading. "${x}" writes ISO 8601: 2025-03-28T09:12:44Z for a Timestamp, 2025-03-30 for a LocalDate, 14:30:00.25 for a LocalTime, the fraction of a second without its trailing zeros, 2025-03-30T10:00:00+02:00[Europe/Paris] for a Zoned (RFC 9557), and X.parse(s), through the Parse contract, reads this form back, ! TimeParseError; a Timestamp is also read back with an offset, 2025-03-28T11:12:44+02:00, and a Zoned’s offset must be that of its time zone. Another format is a fmt"…" literal (5.4), checked at compile time: named fields in braces, {year}, {month}, {day}, {hour}, {minute}, {second}, {nanos}, {weekday}, {offset}, {zone}, with a width, {month:02} with zeros or {day:2} with spaces, or the length of a name, {month:short} (Mar), {month:long}, {weekday:short}; {month} is its number, {weekday} its name, {nanos} its nine digits and {nanos:3} the first three, {{ a brace. No yyyy, MM and mm, whose case confuses months and minutes: an unknown name is a compile error, which gives the right one (the year is written {year}). The literal’s type states the field families it reads, Format<DateFields>, Format<DateTimeFields>… and x.format(f) as well as X.parse(s, f) accept only those their type fills: {hour} on a LocalDate is a compile error. parse checks that the text gives what is needed, the year, month and day of a date, and that a weekday it reads is the right one. Month and day names are in English; localized names will come with locales (section 10).
  • The clock. Clock is a contract, now(): Timestamp, monotonic(): Monotonic, zone(): String, the local time zone as the system names it, which TimeZone.local() resolves, and timer(after: Duration): WaitSource, the deadline a sleep waits on; weaver.time declares task val clock: any Clock = SystemClock. Timestamp.now(), Monotonic.now(), TimeZone.local(), LocalDate.today(in:), sleep and task deadlines read it. A test binds a clock, clock.bind(FixedClock(t, zone: "Asia/Tokyo"), () => …), stopped, whose sleep really sleeps, or a ManualClock(start: t), which advance(5.minutes()) moves forward and whose sleeps then wake up, without really waiting; the tasks launched within the bind inherit it (8.2). No code has to receive the clock as a parameter to be testable.
  • Randomness. weaver.random: Random.bytes(n) comes from the system’s cryptographic generator, for a key or a token; Random.int(in: 1..=6), Random.float(), Random.bool(), Random.shuffle(&xs) and Random.pick(xs) from xoshiro256**, fast but predictable from its output, one per thread, seeded from the system. Rng.seeded(42) is such a generator as a value, whose sequence its seed decides on every machine, for a test or a simulation: var g = Rng.seeded(42), g.int(in: 0..10). An integer is drawn without bias.
  • UUIDs. weaver.uuid (RFC 9562): Uuid.v4(), random, from the system’s generator; Uuid.v7(), its first 48 bits the Unix time in milliseconds, so that UUIDs sort by when they were made; written and read in their usual form, "${id}" and Uuid.parse(s), bytes(), version(), a v7’s timestamp().
  • Logging. weaver.log is a facade: code logs through a named logger, val log = Logger.forModule(), log.info("listening on ${addr}", ("port", .IntV(port))), log.error(e, "saving ${id}"), whose message and fields are lazy; the task val handler: any LogHandler receives the events, filters them by logger and level, and writes them. A level is a severity, nothing more: fatal does not stop the program. An error logged carries where it arose, its location(). The default handler writes a line per event on stderr, at the levels WEAVER_LOG gives, warn,weaver.net=debug,app.db=off; a test binds a MemoryHandler, an application its own handler, handler.bind(h, () => run()), which its tasks and libraries follow; a fuller handler lives outside std. A program that reaches weaver.log logs its panics there, at the fatal level, with their position.
  • Task time. sleep(d).await! suspends the task, without blocking its thread; it is a cancellation point, which yields at once. Among other sources, a deadline is Timeout: await any(rx.receiving(), sleep(d)) waits for a message at most d. withTimeout(d, job) launches job in a task, () => T or () => T ! E, and returns T ! E | Timeout | Cancelled: at the deadline, the task is cancelled and awaited up to its next cancellation point. It binds for that task weaver.time’s task val deadline: Timestamp?, seen by the tasks it launches, the nearer of two deadlines winning; a late task is cancelled, which Task.current().checkCancelled() sees. pool.shutdown(within: d) bounds the disposal of a pool (8.2).
  • What it is not. No leap seconds, no calendars other than the Gregorian, no “today’s date” without a time zone: LocalDate.today(in: zone) requires one, since today’s date depends on the place. Meta code does not read the time (5.5).