Wado

Affine Types

An affine type is move-only: a value of it is used by value at most once. An affine resource is one, as is a type that implements Drop, and so is every type that holds one at any depth. The rest of this chapter follows from four rules:

Rationale: WEP: Affine Types.

Declarations

A named struct or variant that holds an affine value in a field or a case is declared affine. One that holds none may not be, unless it implements Drop. Either mismatch is an error naming the declaration (AFFINE_DECLARATION). A field typed by a type parameter holds nothing for this rule, since the parameter is copyable unless an instantiation says otherwise. A tuple, an anonymous struct and a newtype have no declaration to mark, so each is affine when something it holds is.

affine struct Holder {
    c: Counter,
    n: i32,
}

affine variant Slot {
    Empty,
    Held(Holder),
}

affine struct Bag {
    items: List<Counter>,
}

type Wrapped = Holder;

test {
    let slot: Slot = Empty;
    assert slot matches { _::Empty };
    let bag = Bag { items: [] };
    assert bag.items.is_empty();
}

Moves

The positions that take a value are a binding, a by-value parameter, a return, an element of an aggregate, a by-value self, an as cast, a by-value pattern, and the handler of a with. Using a place after a move out of it is a compile error (TYPE_MISMATCH).

pub resource Counter {
    fn bump(&self);
    fn consume(self);
}

fn eat(c: Counter) { }

fn misuse(c: Counter, d: Counter) {
    eat(c);          // moves `c`
    c.bump();        // ERROR: affine value `c` used after it was moved
    d.consume();     // a by-value `self` moves `d` too
}

The check follows control flow, and tracks each place: a binding, or a field path under it. Moving h.f out of an owned h leaves its other fields usable. Storing into a place makes it usable again.

A closure body and a match guard see what they reach by reference, so neither moves it. A global is never read by value, since no check follows it across functions.

A match or if let consumes its scrutinee as an arm is entered. A refutable pattern that fails consumes nothing, so the else of an if let or a let ... else still holds the scrutinee. A matches consumes nothing, whether it matches or not.

No Move Out of a Reference

Reading an affine value by value through a & or &mut, &self included, is a compile error. Indexing reads an element through a reference, so list[i] is such a read too.

affine struct Holder { f: Fields }

impl Holder {
    fn peek(&self) -> Fields {
        return self.f;       // ERROR: cannot move affine type `Fields` out of a reference
    }
}
impl Holder {
    fn into_fields(self) -> Fields {
        return self.f;       // OK: the holder is consumed
    }
}

test {
    let holder = Holder { f: Fields::new() };
    assert holder.into_fields().copy_all().is_empty();
}
fn first(list: List<Fields>) -> Fields {
    return list[0];      // ERROR: cannot move affine type `Fields` out of a reference
}

A value a call returns belongs to the caller, even when the call took it out of what a reference reaches.

fn take_last(list: &mut List<Fields>) -> Option<Fields> {
    return list.pop();   // OK: `pop` takes the element out
}

test {
    let mut list: List<Fields> = [];
    take_last(&mut list);    // the result nothing binds is dropped
    assert list.is_empty();
}

Generic Code

A type parameter written affine T admits an affine type argument, and its body is checked with T affine. An associated type written affine type Item; is affine the same way.

fn wrap<affine T>(x: T) -> Option<T> {
    return Option::Some(x);
}

test {
    let f = wrap(Fields::new()).unwrap();
    assert f.copy_all().is_empty();
}

A type parameter or an associated type without the mark may be copied. An affine argument for one, or an impl binding an affine type to one, is an error naming it (AFFINE_ARGUMENT). A trait's parameter is one too: impl Tr<Conn> and a bound S: Tr<Conn> are errors under trait Tr<T>.

fn dup<T>(x: T) -> [T, T] {
    return [x, x];
}

export fn run() {
    let pair = dup(Fields { n: 1 });
}

The mark belongs to the parameter's declaration, not its name: a method's T that shadows its impl's affine T is unmarked unless written so. An impl method restates every affine its trait's method declares, since a call through the trait may hand it an affine argument.

An impl whose type parameter is unmarked does not apply to an affine argument, so its methods are not found on that instance. A trait's mark does not reach the parameter an impl binds to it: under trait Sink<affine U>, impl<U> Sink<U> may copy its U, and a call handing it an affine one is the error.

struct Cell<affine T> {
    value: T,
}

impl<T> Cell<T> {
    fn twice(&self) -> [T, T] {
        return [self.value, self.value];
    }
}

export fn run() {
    let cell = Cell { value: Fields { n: 1 } };
    let pair = cell.twice();
}

An affine type implements only an affine trait, whose default bodies and signatures treat Self as affine. Implementing a trait without the mark for an affine type is an error at the impl (AFFINE_DECLARATION).

affine trait Named {
    fn name(&self) -> String;

    fn shout(&self) -> String {
        return `${self.name()}!`;
    }
}

impl Named for Holder {
    fn name(&self) -> String {
        return "holder";
    }
}

test {
    let h = Holder { f: Fields::new() };
    assert h.shout() == "holder!";
}

Drop

The owners of a value are a parameter, a local, a temporary and an aggregate. An owner stops holding a value at the first of these:

The owners that stop together drop in the reverse of the order they began holding. A trap does not unwind, so it runs no drops.

A temporary a let keeps borrowed stops holding its value when the let's scope ends, as a local declared there would, after the let's own bindings. The let keeps the borrow written as its initializer, or as an operand of a struct, tuple or list literal or of a cast that it keeps, and the temporary borrowed is the operand of that & or &mut, or what a field read (a tuple's constant index among them) or a dereference of the operand reads from. This is Rust's temporary lifetime extension. A temporary only a call's operand borrows is not kept, whatever the call returns.

test {
    blk: {
        let a = &make(1);
        let b = &mut make(2);
        b.n += 10;
        let [c, d] = [&make(3), &make(4)];
        let p = Pair { a: &make(5), b: &make(6) };
        let n = &make(7).n;
        let xs: List<&Tok> = [&make(8)];
        assert DROPPED.is_empty();
        assert [a.n, b.n, c.n, d.n, p.a.n, p.b.n, *n, xs[0].n] == [1, 12, 3, 4, 5, 6, 7, 8];
    }
    assert DROPPED == [8, 7, 6, 5, 4, 3, 12, 1] as List<i32>;
}
test "a struct pattern drops the fields it leaves out" {
    let d = DROPS;
    let p = P { a: Tok { id: 1 }, b: Tok { id: 2 } };
    match p {
        P { a, .. } => {
            assert DROPS - d == 1;
            assert eat(a) == 1;
            assert DROPS - d == 2;
        },
    }
    assert DROPS - d == 2;
}

What a drop does is the type's Drop, a prelude trait:

pub affine trait Drop with () {
    fn drop(self);
}

A drop's effects are ambient: a function declares no effect for a drop it performs, written or implicit. Drop::drop is declared #[ambient(_)], so an impl's body performs what its release needs without declaring it.

References into Affine Values

A value refers into a local when it is a reference to the local or to a place inside it, a closure capturing it, or a value built from one whose type may hold a reference: a struct or tuple holding one, or what a call returns when it was handed one. A call may store what any of its operands refers into through each &mut it takes.

A borrow &x or &mut x handed to a parameter declared &P or &mut P stays out of the result where the declared return type holds no reference that could point into a P: none to P itself, to a type a P holds, or to a type parameter. It is likewise never stored through another parameter declared &mut Q where Q holds no such reference. Such a result, or such a Q, still carries what x refers into. A parameter declared a type parameter, or a callee that is a closure or a fn value, hands the borrow on.

test {
    let mut t = Tok { id: 1 };
    let n = Name { text: "a" };
    let id = read(&mut t);
    let v = view(&t, &n);
    let w = t.label(&n);
    let x = Tok::label(&t, &n);
    let moved = t;
    assert id == 1;
    assert v.name.text == "a";
    assert w.name.text == "a";
    assert x.name.text == "a";
    assert moved.id == 1;
}

A value referring into an affine local is read only while the local holds what it read. The compiler refuses (TYPE_MISMATCH):

test {
    let t = Tok { id: 7 };
    let r = &t;
    builtin::drop(t);
    assert r.id == 7;
}

A borrow of an affine temporary refers into it as into a local whose scope is the temporary's statement, its iteration where a loop's head holds it, or the let's scope where a let keeps the borrow, and the same rules hold. A temporary is any value no place holds: a call's result, a literal, what ? unwraps. A cast converts for free, so borrowing one borrows its operand.

test {
    let r = id(&make(1));
    assert r.n == 1;
}
fn tried() -> Result<i32, String> {
    let r = id(&(make(1)? as Alias));
    return Ok(r.n);
}

test {
    assert tried().unwrap() == 1;
}