Skip to content
Weaverv0.5.0

Memory model

Weaver has neither GC nor lifetimes. Every value has a single owner, references live only for the duration of a call, and the heap is managed by reference counting that the compiler infers and elides.

memory-model.md drafts a revision of this section and of section 7: frees placed at the end of the owner’s scope, copies written, sharing declared where a value is placed, and a migration in phases. This section describes the model in force until then.

  • Logical copy. Assigning or passing a value copies it logically. Scalars are actually copied; String, Array, Map and the records that contain them move when their last use gives them up, and are otherwise shared by count, a write going in place (memory-model.md). x.copy() writes a copy, of any value but a resource, its blocks its own down to the positions no code writes in place; the compiler requires it where a value modified still serves its source (6.3); a type’s own method copy comes first.
  • No mutable aliasing. Two names never designate the same mutable value. A modification is therefore never seen “at a distance”.
  • No cycles. Values cannot form a cycle. Graphs go through handles (6.4).
  • Shared views. data[a..b] (or data.view(a..b)) returns a value of the same type (Bytes, String or an array) that shares the storage of data, without copying. The bounds count elements, or bytes for a string; a string view that would split a character stops the program. It is a value, not a reference: it can be stored and returned freely, and the storage lives as long as a view exists. A view is a result lent by data (6.3), like the conversions s.bytes(), b.utf8() and s.trim(): a view modified, or kept while data is modified in place, is copied, .copy(); views are taken once the buffer is frozen. A view costs a pointer, a length and a shared counter.
type Chunk = { lines: Bytes[] } // a chunk that holds its own lines
fn seal(sink data: Bytes, spans: Range<Int>[]): Chunk =
Chunk{lines: spans.map(data.view(?))}
Convention Declaration Call Meaning
read (default) fn show(u: User) show(u) Read borrow, no copy
mutation fn normalize(u: mut User) normalize(&u) Exclusive access, its content modified in place, the value never replaced
consumption fn save(sink u: User) save(u) The value is moved, u is no longer usable; a value without a counted part, a scalar or a record of scalars, is copied, and remains usable
deferred fn debug(lazy msg: String) debug("…") Evaluated at most once, on first read (6.6)
consumption and disposal fn merge(using runs: Run[]) merge(runs) Like sink; if the body does not consume the value, it is disposed of at the end of the function (7.2)

The & at the call site is the language’s only memory sigil. It makes the mutation of an argument visible where it happens.

Modified, never replaced. A mut parameter modifies the content of the value its caller lends: u.name = n, xs[i] = v, xs.push(x), xs += ys on an array, a string or bytes, a mut method. It never replaces the value: u = other, n += 1 on a scalar, self = … are rejected, with the advice to return the new value, which the caller stores, n = next(n). A scalar, or an enum without data, has no content apart from its value: a mut parameter of such a type is rejected. Replacing goes through a return, or through core’s replace(&place, with: v), which returns what the place held, the one replacement through a parameter, which its name says; unsafe code may replace too. A lambda’s mut parameter follows the same rule; a guarded value without content changes through update, counter.update(c => c + 1) (8.3). Where a parameter may be replaced, C#’s ref, out parameters, the callee changes behind its caller’s back what its label designates (memory-model.md, section 3).

A view as mut. r.read(&buf[carry..]) passes part of an array, or of a string, shout(&s[0..7]), whose bounds do not split a character: the callee receives the view, and its final contents replace those of buf[carry..], in place if it keeps its length, by rebuilding buf otherwise. As with any mutation, buf is not used otherwise during the call (6.3).

Receiver mutation. In a dotted call x.f(…), the receiver carries no &. Its mutation is controlled on both sides:

  1. At the declaration. A function that modifies its receiver declares it: mut self in a contract, mut on the first parameter of a free function (3.1). It is never inferred, because changing that signature changes the API’s contract.
  2. At the call. The receiver must be modifiable: a var, a val whose content is mut, a using binding, a mut parameter, or a field of such a value. On a val without mut, the error suggests declaring it mut.
  3. Conversely. A var binding that is never modified triggers a warning, so that var remains a reliable signal.
  4. No temporary. makeScanner().scan(…) is rejected: the modification would be lost.
  5. When reading. The IDE marks the call with a mut hint.

A reference can be neither stored in a field nor returned. No lifetime annotation is therefore needed. Access to part of a value goes through projections:

impl Index<String, Int> for Counter {
subscript(self, k: String): Int { yield self.map[k] ?? 0 }
subscript(mut self, k: String): mut Int {
var n = self.map[k] ?? 0
yield &n // the caller modifies n…
self.map[k] = n // …then the projection stores it back
}
}
counts["weaver"] += 1 // mut projection, no reference escapes

A read subscript returns its value with yield, like return. A projection yields a location, once only, at the top level of its body: the caller’s code runs in place of the yield, then the rest of the body, which can store back what changed. An iterating projection, a property each, yields in a loop, each element in turn, yield (e.key, &e.value), a tuple whose parts are values read or places, &x, modified: a for with a mut binding, for (k, mut v) in m, runs its body at each yield; continue ends a turn, the projection’s code after its yield running, break leaves the projection’s loop from its yield, the code after that loop still running, and return leaves the function. It is not a function but a template: each use, a[k] = v, a[k] += 1, f(&a[k]) or a[k].push(x), inserts its body, with the assignment or the call in place of the yield. A mut pattern binding, if m[k] is Some(mut s) { s.hits += 1 }, lives for the whole arm: the rest of the body runs on leaving the statement, like a defer, on every path, return included. This modifies a Map entry in place, without copying it into a variable and then storing it back. Map<K, V> (weaver.collections) has one: m[k] returns a V?, m[k] = v stores, m[k] = None removes the entry. Its keys adopt Eq and Hash; its iteration order is unspecified. Set<T> is built from it.

Properties. A property is a named projection, read and written as a field: property count(self): Int { yield self.state.count } is read by m.count, a function whose body may record what it read; property count(mut self): mut Int { yield &self.state.count; self.changed("count") } is the place of m.count += 1, m.tags.push(t) or bump(&m.count), inserted at each use, the rest of its body running after, which notifies. A property without its mut self form is read-only. It takes no key, and does not take a field’s name; record literals, with, ..source, record patterns and a type’s fields in meta code see the fields only. On a shared mut model (6.4), the observers designate the value its properties change.

A type may have several subscripts, one per type of key, t[r] choosing by the key’s type, the type of r read first. The exclusivity rule is local: during a mut access, no other access to the same value is allowed. The compiler checks it without interprocedural analysis. It applies to field paths: p.x and p.y are two distinct values, and swap(&p.x, &p.y) is allowed. Two elements of an array are assumed to overlap: swap(&xs[i], &xs[j]) is rejected; the array offers xs.swap(i, j). The access begins when the call does, in two phases: the path of the mut place is evaluated in argument order, its indices included, then the other arguments, then the place is resolved, its index checked, and lent. An argument may therefore read the place, or modify it, as long as what it gives the call no longer designates it: w.insert(w.start, x), m[k] = (m[k] ?? 0) + 1, a.push((a.pop() ?? 0) * 2), a[1].push(a.pop() ?? 0), which resolves a[1] after the pop. Only a read argument that is itself a place holding a heap block of the value lent is rejected, move(&p, p.items): the callee would read it as it modifies it. Likewise, a value read for a call, the receiver included, cannot be modified by a later argument, c.show(c.bump()): the call would receive it as it was before; that argument is computed first, val k = c.bump() then c.show(k). A copy the memory model requires is written, .copy(), and its absence is an error (memory-model.md): a binding modified while its value is another’s, val ys = mut xs; a binding read after its place is modified in place, val before = xs then xs.push(4); a loop over a place its body modifies; a value stored into an object while it still serves, or modified in place afterwards. A result a call lends, : yield T, x.unwrap() or x ?? y, is a part of the place it comes from, held by count, and so are the bindings of a pattern that matches it, if b.utf8() is Some(s): a binding modified in place, a store or a sink argument copies it, unless the value is taken out first, replace(&x, with: None) ?? []; a function returning parts of self declares its result lent, or copies it.

To keep part of a buffer durably, take a view (6.1). To designate it for the duration of a computation, a function returns a range and the caller slices: val k = key.bounds(line) then line[k].

  • Inferred counting. The compiler inserts the increments and decrements, then removes those it proves useless. Reading a value borrows it without counting; storing or returning it takes a reference, or moves the value when it is not read afterwards (a temporary, a returned variable).
  • In-place reuse. A unique value is modified in place: xs.map(f) on a temporary, unshared array reuses its cells when its elements and their images have the same size, parse(lines).map(f).map(g) making only one array. A loop that writes a variable’s array by index checks only once that it is not shared, then again after each statement that uses it otherwise.
  • Inferred atomicity. Counting is atomic only for values that cross tasks.
  • Graphs. Arena<T> (weaver.collections) stores nodes addressed by Handle<T>. A handle is a value (a generational index), hence copyable and without an ownership cycle: var g = Arena<Node>.new(), g.insert(v) returns the handle, g[h] reads or modifies the node, g.get(h) returns T?, g.remove(h) returns it and frees its slot, which a later insert reuses with one more generation. Reading through a removed handle stops the program. An arena of nodes is not a resource, and its memory follows counting like an array’s. An arena object, arena type Tree = { root: ref Node? }, owns the region of its nodes, which designate each other by ref Node, an index into it, core’s Ref<Node>: type Node = { name: String, children: ref Node[], parent: ref Node? } forms a cycle without a count. t.add(node) stores a node and returns its ref, t[r] reads it or modifies it in place, t[r].children.push(c); a copy of the object copies its region, its refs staying valid; a ref of another object stays memory safe, the region’s index being checked, but may designate the wrong node (memory-model.md). An object may hold several types of node, a region for each, add then generic over them, and be generic, arena type Graph<T> = { start: ref Vertex<T>? }. An object declared @removable removes nodes: t.remove(r) takes a node out, None if r designates none any more, and frees its slot, which a later add reuses; its refs then carry the generation of their slot, #0·1, checked at each access, a ref of a removed node stopping the program. Only such an object pays that check.
  • Identity. A shared mut T value is one value that its holders designate (memory-model.md, sections 7 and 9): val root: shared mut Node = Node{name: "root", children: [], parent: None} gives the record up to it, a copy designates the same value, and a modification through any holder, root.children.push(leaf) or alias.name = "A", is the value’s, seen by all. a === b says whether two designate the same value, a !== b the opposite; == compares the values they hold. It reads and modifies as the value it holds, root.name, xs.push(1), &xs for a mut T[] parameter; a lambda that captures it modifies it too. It stays on its task: a task’s lambda does not capture it, an async fn does not receive it. A modification that overlaps another of the same value, a callback modifying the value being modified, stops the program. A weak field, weak parent: Node?, designates a shared mut Node without keeping it: parent: weak root sets it, reading it gives a (shared mut Node)?, None once the value is freed, at its last strong holder. Strong shared mut fields around a cycle of types, children and parent both strong, are refused, the error naming them: one of them is weak. A field designating its own type, a tree’s children, is not a cycle.
  • unsafe. Raw pointers Ptr<T> and C FFI, only inside an unsafe block. A Ptr<T> is read (p.load()), written (p.store(v), which takes a reference to v), advanced (p.offset(n)), changes pointee type (p.cast(), to the expected type), and counts the references of the pointed-to value (p.retain(), p.release()). This is how core writes T[] and String in Weaver.

The editor shows at the end of a line what its code costs, computed on the lowered code: heap when a call may allocate on the heap, copy when the line certainly writes a shared block, and rc n for its reference-counting operations. What a function of the program costs is read on its own lines, not on its call. At a call, an argument passed to a lazy parameter (6.6) is marked lazy before it: nothing in the call says that it may not be evaluated. An in-place write has no mark: it only checks whether its block is shared, which copy and @assert(nocopy) cover when it matters, and marking every possible copy would bury the certain ones; neither does an [var x] capture, which the text already shows. Critical code can require its costs:

@assert(noalloc, nocopy)
fn mix(out: mut Buffer, a: Buffer, b: Buffer) { ... }

@assert(noalloc) is checked on the lowered code: no path of the function, nor of the functions it calls, allocates on the heap. A path that ends in a panic does not count. Calling a function value follows what is known about it: a lambda written at the call site, xs.count(x => x > limit), is checked where the callee calls it; a value about which nothing is known, read from a field or an array, is treated as an allocation. The error shows the path to the allocation: arrayPush<Int> → grow<Int> → newBlock → wv_sys_alloc.

@assert(nocopy) applies to value copies. A value is copied by .copy(), which the source writes where the memory model requires it (memory-model.md), and when a view or a literal is written, which copies it first: that path is taken at run time, depending on what the value is. In a nocopy function, and in what it calls, it stops the program: shout(s: mut String) appends to s in place, and stops if the caller passes it a literal. The check rejects the explicit copies, .copy() in the function or in what it calls:

@assert(nocopy)
fn touch(xs: Int[]): Int {
val ys = mut xs.copy() // `.copy()` of `Array<Int>`
ys[0] = 7
return ys[0]
}

A lazy parameter is evaluated only if the callee reads it. This avoids guard ifs and wrapping lambdas, notably in logging.

contract Logger {
fn enabled(self, level: Level): Bool
fn write(self, level: Level, msg: String)
inline fn debug(self, lazy msg: String) {
if self.enabled(.debug) { self.write(.debug, msg) } // msg evaluated here, and only here
}
}
log.debug("state: ${state.dump()}") // no if, no lambda
  1. Evaluated at most once. The argument is computed on first read, then memoized (call by need). If it is never read, it costs nothing.
  2. No allocation. A lazy parameter is second-class, like a reference (6.3): it can be neither stored nor returned. Its thunk therefore lives on the caller’s stack.
  3. Zero cost if the callee is inline. The expression is copied where it is read, without a thunk: an inline fn is inlined at each call, and the thunk with it.
  4. No hidden effects. An expression passed as lazy can contain neither a & mutation, nor a mut call, nor !, nor return, nor break. Since mutations are marked at the call site (6.2), the check is local. The IDE flags the argument with a lazy hint.
  5. Explicit escape. To keep a deferred computation, create a Lazy<T> value with lazy { … }, a block whose value is its last expression, like an if’s, and which reads as Lazy.new(() => value of the block): it captures like a lambda, by copy, a return in it returns the value, and a ! makes it a Lazy<T ! E>. It is memoized and allocated, and its type shows it: x.get() computes the value on first read and returns the same one afterwards, x.isEvaluated() says whether that has happened. Its copies share the computation, which happens only once even when read from several tasks; once done, reading it no longer takes a lock.
  6. A literal by default. A lazy parameter’s default value is a literal, None, [] or [:]: lazy fields: Field[] = [].
  7. Forbidden for a Disposable value. A resource created only if the argument is read would make linearity (7.1) uncheckable.

Library operators. Short-circuiting is no longer a special case in the compiler: &&, || and ?? are ordinary functions with a lazy parameter, tied to their symbol by @operator (section 4).

@operator("&&") inline fn and(a: Bool, lazy b: Bool): Bool = if a { b } else { false }
@operator("??") inline fn orElse<T>(o: T?, lazy fallback: T): T = match o {
Some(v) => v,
None => fallback
}
val port = cfg.port ?? defaultPort() // defaultPort() only if needed
val config = cache.getOrInsert(key, load(key)) // getOrInsert(k, lazy v)
assert(xs.isSorted(), "not sorted: ${xs}") // message built only on failure
val user = opt.okOr(NotFound("user ${id}")) // error built only if None

Compile-time filtering. Combined with meta if, a minimum level fixed at build time removes the calls entirely. The run-time threshold, for its part, avoids evaluating the argument.

#Eq #Ord #Parse
enum Level = | debug | info | warn | error
meta val MinLevel = Level.parse(Build.env("LOG_LEVEL") ?? "info") catch _ => .info
inline fn debug(self, lazy msg: String) {
meta if MinLevel <= .debug { // call entirely removed below the threshold
if self.enabled(.debug) { self.write(.debug, msg) }
}
}