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:
- A position that takes a value moves it. Every other position reads the value where it stands.
- A value has one owner. A reference owns nothing, so no value moves out through one.
- A value that has not moved drops exactly once, when its owner stops holding it.
- Code that may copy a value is not handed an affine one.
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:
- Its scope ends, on any path out of it. A function's parameters are the outermost locals of its body.
- It is a temporary or a value its statement discards (
make();,let _ = make();), and its statement ends. Awithowns a handler it is given by value the same way. A temporary aletkeeps borrowed is the exception, below. - It is a temporary in a loop's head, and its iteration ends: after the body,
and in a C-style
forafter the update too. The head runs once per iteration: awhilecondition or let chain, or a C-styleforcondition. Aforupdate is a statement of its own. A for-of evaluates its iterable once, as part of the for-of statement. - An assignment replaces it:
x = valuedrops whatxheld, and a store into a field or an element drops what the slot held. - It is the part of a by-value pattern that no binding takes. It drops as the
arm is entered, after the guard, or as the
letbinds. - What holds it drops.
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 type with an impl runs its
drop. The body may move fields out ofself, and the fields left at its end are dropped. A pattern may takeselfapart, but nothing may hold it whole, since wherever it went it would rundropagain. - A type without an impl drops its fields in declaration order.
- Only an affine type implements
Drop, since a copyable type would run it for every copy. A type that implements it is never partially moved, outside its owndrop: no field read, pattern or..basetakes an affine part of it. builtin::drop(value)drops any value where it is called.
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):
- a read of it after the local moved, or after the local's scope ended;
- a read of it after an assignment to a place holding what it reads, which drops the old value. A read of the assigned place itself is still allowed, since the assignment writes in place, unless that place had moved;
- a read of it after a
&mutuse of the local other than through it, such as a method taking&mut self, which may have moved out a part of the local; - a
returnof it from the body declaring the local; - a
&mutparameter, or a closure's capture, left holding it when the body ends; - a store of it into a global.
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;
}
