Ownership
Every value in Rux has exactly one owner: a binding, a parameter, a field or element of a larger value, or a temporary that nothing has named yet. The owner decides when the value's life ends, and at that point the compiler destroys it — once.
A value passes from one owner to another in one of two ways. A copy makes a second, independent value and leaves the source as it was; only plain data copies. A move, written move source, hands the value itself over and leaves the source empty. A reference is the third way to reach a value — it borrows without owning, so nothing changes hands.
Syntax
let name = source; // bind a copy
let name = move source; // bind by moving
target = source; // copy assignment
target = move source; // move assignment
F(source) // pass a copy
F(move source) // move into the parameter
return source; // return a copy
return move source; // move out of the function
Type { field: move source } // move into an aggregate
match move source { … } // hand the subject to the arms
= always initializes or replaces its destination; move always says the source is consumed. move is a prefix operator with the precedence of every other unary operator, so move a.b moves the field a.b, move a + b is (move a) + b, and (move x)? moves the optional before propagating it. It is a reserved word, so it cannot name a binding. The old arrow is not an operator: let x <- y; is '<-' is not a binding operator with help: write 'let name = move source', and a <- b; is '<-' is not an assignment operator with help: write 'target = move source'.
Copy or move
A named source is copied unless it is written move source, and only plain data copies: numbers, bool, characters, raw pointers, slices, function values, and structures, tuples, variants, unions, optionals and arrays made only of them. Every other type is move-only — a type with a destructor owns resources, and so does anything holding one — so a named move-only source in any by-value position is an error without move. Copying never touches the source: both values exist afterwards, and changing one never shows in the other. Moving invalidates the source, suppresses its destruction — the new owner destroys the value instead — and makes every later read of it an error.
#NoCopy
struct Token {
id: int32;
}
func Consume(token: Token) {
PrintLine("consumed {}", token.id);
}
func Main() -> int {
let first = Token { id: 1 };
let second = move first; // first is now empty
Consume(move second); // second is now empty
return 0;
}
flowchart LR
a(["`a`: a value<br/>with a name"])
a -- "`let b = a`<br/>copy" --> c["two values<br/>`a` and `b` both usable"]
a -- "`let b = move a`<br/>move" --> m["one value, now `b`'s<br/>`a` is empty"]
a -- "`let b: &T = a`<br/>borrow" --> r["one value, still `a`'s<br/>`b` refers to it"]Copy = | Move move | Borrow &T / &var T | |
|---|---|---|---|
| Values after | two | one | one |
| The source | unchanged and usable | empty; reads fail | still the owner |
| Destroyed by | each owner, its own | the new owner only | the original owner |
Whether a type copies or only moves is decided by what it holds, and two attributes take a capability away: see Copy and move. Moving works for every type that does not prohibit it, a copyable one included — let m = move n; with an int n leaves n empty too. A move is always a byte copy of the value followed by forgetting the source; no user code runs.
Fresh temporaries
A value nobody has named — the result of a call, a literal, a constructor call, or the value a conditional or match produces — has no other owner, so it transfers directly. It needs no move, and no copy runs:
func Make(id: int32) -> Token {
return Token { id: id }; // a literal: no 'move'
}
func Main() -> int {
let token = Make(7); // a call result: no 'move'
Consume(Make(8));
return 0;
}
move is for values that have a name. It marks, on the line where it happens, which names stop working.
After a move
Reading a moved-from name is a compile-time error. The note points at the move:
error: value 'first' is used after it was moved
note: 'first' was moved at …
help: clone 'first' before moving it if both uses are required
A moved-from var is empty, not ruined. Assigning it a whole new value makes it usable again:
var token = Token { id: 1 };
let held = move token;
token = Token { id: 2 };
PrintLine("token is {} again", token.id);
Moves on some paths
The compiler tracks moves through branches and loops. A value moved on one path of an if is unavailable after the if, because the compiler cannot know which path ran:
error: value 'token' may have been moved on some control-flow paths
A loop body runs again from where its last pass ended, so a value one pass moves out is not there for the next. Moving an outer local inside a loop body is an error unless the same pass gives it a new value before the loop repeats, or leaves the loop with break, return or throw after the move. The loop's own for variable and the locals declared inside the body are fresh on every pass.
var slot = Token { id: 3 };
for pass in 0..2 {
let taken = move slot;
PrintLine("pass {} took {}", pass, taken.id);
slot = Token { id: 10 + pass as int32 }; // refilled before the next pass
}
At run time a value moved on only some paths is tracked by a drop flag, so it is still destroyed exactly once — see Destructors.
What cannot be moved
| Written | Error |
|---|---|
return move reference; | cannot move a non-owning reference |
let a = move value.field; | cannot move field 'field' out of 'value', which is destroyed as a whole |
value = move value; | cannot move 'value' into itself |
let b = move pinned; | moving type 'Pinned' is prohibited |
move buffer while borrowed | cannot move 'buffer' while it is immutably borrowed |
A reference owns nothing, so there is nothing to hand over. A single part cannot leave a value on its own; the value is moved whole or taken apart. A type can prohibit moving altogether.
See also
- Copy and move — which types copy,
Clone, and how a type forbids copying or moving - Destructors — what happens when an owner lets go
- Defer — cleanup that belongs to a scope rather than a value
- References — reaching a value without owning it
- Learn: Ownership, Copy, Move
Type Tests
The is operator: which member of a sum is active, whether an optional is present, a static check of a value's exact type, or a test against any pattern that binds names where it holds. It never narrows.
Copy and Move
Plain data copies and every other type moves. Clone duplicates an owning value, #NoCopy and #NoMove take a capability away, and neither operation ever runs user code.