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.
8.1 Errors
Section titled “8.1 Errors”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,OkandErrtake their type from the context (annotation, parameter, return type, including throughif,matchand blocks);Some(x)also infers it from x. The success of a() ! Eis writtenOkorOk(()), and matched byOk,Ok(_)orOk(()). These four names belong to the prelude: an enum cannot reuse them. !is the only propagation.x!returns the value ofx, or leaves the function with its error. A type that adoptsTry<T, E>(core),fn toResult(sink self): T ! E, propagates the same way:x!isx.toResult()!. Every point where an error can rise stays visible. The error must be part of the declared union, or convert into it throughFrom.- Error unions.
User ! DbError | ParseErrorcomposes without a wrapping type. A union is a type whose members have no order and no duplicates (A | BisB | A,A | (A | B)isA | 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()ande.location()exist on every union, each member being anError. A generic can open the union:fn orZero<E>(r: Int ! E | Timeout), called with anInt ! DbError | Timeout, infers E = DbError. - Conversion.
contract From<E> { fn from(e: E): Self }(core) converts an error:!,failand returning aT ! E'callfromwhen the function’s error type does not contain E’ but adoptsFrom<E'>, an adoption by the collected error type (section 4). - Result passed through as is. An expression already of type
T ! E', whereE'is included inE, is returned without being wrapped.Okis written only ifTis itself aResult. - A Result is not discarded. A statement whose value is a
Resultand gets lost is an error: its error would be ignored with nothing to show it. It is propagated with!, handled withcatch, or deliberately dropped withval _ = 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 eachx!, the value of eachfail, that of aT ! Ereturned 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 aT ! E, it yields aT ! Context<E>,Context<E> = { context: String, cause: E, at: Location }, at being where.contextis called, and its message is built only on an error. Itslocation()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”; acatchmatchesContext(c)like any other member, thenc.cause. panic. Reserved for bugs (violated invariant, index out of bounds):panic("impossible state"), a core function visible everywhere, whose type isNever, and which records where it is called,Location.caller(). It unwinds the current task up to the nearest barrier, running itsusing,deferanderrdeferon 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. Inabortmode,[package] panic = "abort"in weaver.toml orweaver build --panic=abort, a panic writes its message and callsabort(): nothing runs any more, neitherdefernor 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, aT ! Halt: a panic below it, or aProcess.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 = nextErr(Halt.Panicked(message, at)) => state = safeState() // at: where it aroseErr(Halt.Exited(code)) => shutdown(code)}Haltis an enum of core that adopts Error:Panicked(message, at), at being where the panic was called, itslocation(), orExited(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
setjmpwhen 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,deferanderrdefer, and the system takes the memory back. Locks taken byMutex.withand the other scoped calls of std are released, through their cleanups. - In
abortmode, which writes no landing pad,Panic.catchingis 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 aPanicPolicy(weaver.task)..stop, and a pool withoutonPanic, stop the program as above..isolatekeeps the panic within the task: whoever awaits its promise panics in turn with the same Halt, which aPanic.catchingaround theawaitcatches, and a detached task’s panic is reported like its errors, to the pool’sonError.Pool.global().onPanic(halt => .isolate)sets the global pool’s, at the start ofmain, 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, asProcess.exitdoes forExited. Process.exit(code)unwinds like a panic, running the cleanups, up to the nearest barrier, which receivesExited(code); without one, the program exits with code.Process.exitNow(code)exits at once, without running anything, asexitdid.
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- Exhaustive,
catchproduces aT. - 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. - Arms can exit through
fail,return,!,breakorcontinue. - Short form.
catch pattern => exprfor 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.
#Errorimplements the contract for an enum, from the variant tags (5.6). An error is an enum: a record does not adoptError, core’sUserErrorandContext<E>aside, and#Erroron 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.#Erroralso 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:#Erroris the normal way to declare an error, and animpl Errorwritten 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’serrors.New.fail "empty file"andErr("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.
#Errorenum DbError = | Timeout `error("timed out")` | NotFound(id: Uuid) `error("user ${id} not found")` | Constraint(name: String) `error("constraint ${name} violated")`8.2 Tasks
Section titled “8.2 Tasks”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 fnlaunches a task and yields aPromise<T>:fetchUser(id).await f(x)launches it and awaits it in one go;f(x).awaitis 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 withusing, and its disposal cancels it then awaits it. - Resources and tasks. An
async fnthat receives a resource declares itsink(orusing),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, butd.result(), which would copy it, is rejected. Atask valdoes not carry a resource, shared between the tasks its bind launches; nor does aShared<T>, read through snapshots; both hold it in a shared object. Athread varcarries one, disposed of with its thread, if its disposal cannot fail. An async fn also receives alazyparameter, which the task evaluates when needed. - Fire and forget.
detach f(x)yields aDaemon<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 adoptsShow. The handle observes and cancels,d.isDone(),d.result()(aT?),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.
awaitawaits aPromise<T>, or anything that adoptsAwaitable<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 aTaskScopein.failFast.await any(a, b)awaits together sources of different kinds: promises, receptions (rx.receiving()), deadlines (sleep(d), 8.5), or whatever adoptsSelectable<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 ofInt ! IoErrorand a reception ofString?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.TaskScopeisDisposable: 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, whichawaitAnyandawaitAllOrFailreturn;results(), which would return them in an array of Result, does not accept them.weaver.taskalso providesLatch,BarrierandSemaphore. - 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 throughTask.current().isCancelled(), orTask.current().checkCancelled()!, which fails withCancelled, the enum of weaver.task.awaitis a cancellation point: the awaiting task may have been cancelled in the meantime, and the wait then fails withCancelled.await pon aPromise<T>is therefore aT ! Cancelled, and on aPromise<T ! E>aT ! 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 itsCancelledto 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 poolopens it to other modules, which import it like any other name. WithoutonError, 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 withTimeout. Launching a task on a disposed pool stops the program. Pool.global()exists without declaring anything, sized onSystem.cpuCount(). It returns aPool, which designates a pool without answering for it, likeio.pool(). The program’s pools are created beforemain; aftermain, 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)orscope.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’son p { … }block;Pool.global(). Theonblock 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.
asynctherefore does not say that a function suspends, but that a call launches a task;awaitis written in any function, and also in alazyargument (6.6). A pool chooses its way: one system thread per task, M:N scheduling, or what it does with a blocking system call. Anextern "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 inunsafecode, writes where it happened,segmentation fault at address …then the functions on the stack, whateverWEAVER_BACKTRACEsays, 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, cancellationprint("${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 launchesthread var scratch = Bytes(capacity: 1 << 20) // one per thread, kept from one task to the nextval size = scratch.with(s => s.len())Task.current()designates the running task: its id, its name (that of the launched async fn,spawn, ormain), its pool, its cancellation. The handle is copied, and stays valid after the task ends.task valcarries 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 varis 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 throughscratch.with(s => …), which receives the thread’s value asmut: 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 (awaitis 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, ormainoutside 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’sonThreadStartis called by each thread, on itself, at its start.
8.3 Sharing between tasks
Section titled “8.3 Sharing between tasks”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.Mapimport 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)passesf: (mut T) => Rits 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)andAtomicBool(false)are modified without a lock, in sequential order:load,store,exchange,compareExchange, andadd(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 promiseprint("${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 aPromise<Int>; inside,selfis the state, andself.add(n)calls another method in place, without a task. - Generic.
actor Cache<K, V> = { … }andimpl<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.countis rejected outsideimpl Counter: a method that returns it writes it,fn total(self): Int. A method does not receive amutparameter, which would not survive the task that runs it; it receives a resource assinkorusing, 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().awaitreceives an actor. It derives nothing,#Showor#Eqwould 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 assinkgives a copy of it: whoever gives it up keeps it. - Its fields do not change. The object changes through its methods, which receive
selffor reading and synchronize themselves, inunsafecode: 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
disposethen 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, andTaskandDaemon, 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 lambdaval 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 zeroval step = Barrier(parties: 4) // arrive() waits for all four, then starts overMutex<T>guards a value;m.with(f)passes it tof: (mut T) => Rwith 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-thcountDown(), forever, and is awaited withawait;Barrier(parties: n)gathers n tasks at each round, andarrive()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 aSender<T>and aReceiver<T>, two shared objects: their copies are as many producers and consumers. The channel is closed withtx.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:sendreturns() ! ChannelError,Closed, and v is disposed of. - Receiving adopts.
rx.receive()returns aT?, None once the channel is closed and drained; the message is handed over to the receiver, and is adopted withusingif 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 isTimeoutat 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.
8.4 Entry point
Section titled “8.4 Entry point”| 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)`}
#Clienum Command = /// Adds files to the index | Add(AddArgs) /// Shows the state of the tree | StatusThe 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.
8.5 Time
Section titled “8.5 Time”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 timeval now = Timestamp.now() // the instant, in UTCval 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 changeval inOneDay = meeting + 24.hours() // exactly 24 hours, perhaps another wall-clock timeprint( "${now} ${meeting} ${start.elapsed()}") // 2025-03-28T09:12:44Z 2025-03-30T10:00:00+02:00[Europe/Paris] 3msprint(meeting.format(fmt"{day:02}/{month:02}/{year} at {hour}h{minute:02}"))- Instants.
Timestampis 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()andTimestamp.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()andTimestamp.fromUnix(s, nanos:)go through the Unix epoch; nanoseconds outside one second carry over to the seconds.t + dandt - dmove forward or back by a Duration,b - areturns one. - Measuring.
Monotonicis the reading of a clock that never goes back, untouched by setting the time:Monotonic.now(),m.elapsed(),b - a, which areDurations. It does not tell the time, does not convert to aTimestampand 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.
Durationis a signed number of nanoseconds, ±292 years:250.millis(),5.seconds(),90.minutes(),2.hours(), andnanos,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}"writes1h30m0.25s, like Go,250msor1.5µsbelow one second, andDuration.parse(s)reads it back;d.iso()writesPT1H30M0.25S. There is nodays(): a day is not an exact duration, it lasts 23 or 25 hours at a DST change. - Civil durations.
Periodcounts in calendar units:Period(years: 1, months: 2, days: 3),Period(weeks: 2)being 14 days, writtenP1Y2M3D. 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,LocalTimeandLocalDateTimeare 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 throught.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;MonthandWeekdayare 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 aLocalDate?, neither an exception nor a silently “corrected” date.d.at(t)makes aLocalDateTimefrom 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)returnsNoneinstead.a.until(b)returns the Period between them,a.daysUntil(b)a number of days,d.plusDays(n)moves forward n days. - Time zones.
TimeZoneis a rule of legal time:TimeZone.utc,TimeZone.fixed(hours: 5, minutes: 30), whose parts share one sign,TimeZone.named("Europe/Paris"), which returnsTimeZone ! TzErrorfor an unknown name, andTimeZone.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 asCET-1CEST,M3.5.0,M10.5.0/3), then the/etc/localtimelink, 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, ortzdata = truein 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) andz.isDst(t)tell its rule at an instant. - Instants in a time zone.
Zonedis an instant seen in a time zone:t.in(paris), andz.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 returnsZoned ! ResolveError, whose variantsSkipped(before, after)andRepeated(earlier, later)carry the candidates,e.pick(r)choosing one of them, anddt.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)andin(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,plusalso asks forresolve:; without it, it returnsZoned ! ResolveError. TwoZonedare 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:44Zfor a Timestamp,2025-03-30for a LocalDate,14:30:00.25for 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), andX.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 afmt"…"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. Noyyyy,MMandmm, 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>… andx.format(f)as well asX.parse(s, f)accept only those their type fills:{hour}on a LocalDate is a compile error.parsechecks 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.
Clockis a contract,now(): Timestamp,monotonic(): Monotonic,zone(): String, the local time zone as the system names it, whichTimeZone.local()resolves, andtimer(after: Duration): WaitSource, the deadline asleepwaits on; weaver.time declarestask val clock: any Clock = SystemClock.Timestamp.now(),Monotonic.now(),TimeZone.local(),LocalDate.today(in:),sleepand task deadlines read it. A test binds a clock,clock.bind(FixedClock(t, zone: "Asia/Tokyo"), () => …), stopped, whosesleepreally sleeps, or aManualClock(start: t), whichadvance(5.minutes())moves forward and whosesleeps 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)andRandom.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}"andUuid.parse(s),bytes(),version(), a v7’stimestamp(). - 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 arelazy; thetask val handler: any LogHandlerreceives the events, filters them by logger and level, and writes them. A level is a severity, nothing more:fataldoes not stop the program. An error logged carries where it arose, itslocation(). The default handler writes a line per event on stderr, at the levelsWEAVER_LOGgives,warn,weaver.net=debug,app.db=off; a test binds aMemoryHandler, 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 thefatallevel, 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 isTimeout:await any(rx.receiving(), sleep(d))waits for a message at most d.withTimeout(d, job)launches job in a task,() => Tor() => T ! E, and returnsT ! 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’stask val deadline: Timestamp?, seen by the tasks it launches, the nearer of two deadlines winning; a late task is cancelled, whichTask.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).