Doc Memory, modes, and mutation

A guide for the perplexed.

Do you find yourself writing random punctuation marks in front of types in hopes of making the errors go away? I sure do. So I decided to write some documentation by randomly hitting keys on the keyboard, and having other people fix the errors.

Concepts

Slots

Slots are places where a value can live in memory, like the x in let x = 4 or {y: 3, x: 2}.

References

References are values that "point to" slots. Like all values, they live in (presumably different) slots.

Mutability

If a slot is mutable, its contents may change:

let x_imm = 4;
let mut x_mut = 4;
x_mut = 456;
// x_imm = 456; // illegal

Mutability is shallow, not deep: a mutable slot may contain a reference to a structure with immutable slots, and an immutable slot may contain a reference to a structure with mutable slots.

Initialization

If a slot is uninitialized, you may not read it. For example, if you have let x: int;, you may not read x until you assign to it. This property is enforced at compile-time, so it is conservative.

The name is perhaps a little misleading; in Rust, it is possible for a slot to become uninitialized if it loses the "right" to access its contents, via moving.

Modes

Rust currently supports parameter-passing modes. There are five or six of them: +, -, ++, &, &&, and one that you get if you don't write any funny symbols. What do they mean? It is a mystery.

Data/types

Boxes: @

The expression @2 produces a reference to a immutable slot in the heap. Executing that expression will result in an allocation, but no visible side-effects. Its type is @int.

If you want mutability (which is pretty much the only reason for putting integers into the heap), @mut 2 has the type @mut int. If you have a variable x with that value and type, you can change it with *x = 3.

Uniquely-referenced boxes: ~

Locally, ~2 is the same as @2, but it also means that no other references to that slot exist. So, the following function:

fn f(x: ~int) -> int {
  *x = 8;
  do_lots_of_complicated_stuff_with_callbacks_and_mutations_aplenty();
  ret *x
}

...always returns 8, because no one else has a reference to that slot to change it.

To enforce this, the compiler will give you errors if you attempt to implicitly copy a value with ~ as a type. Explicit copies will also recursively copy through ~s, to avoid duplication.

[]

Manipulating things

Binding: let

The statement let x: int = 3 introduces an immutable slot, named x, and initializes it with 3. You can use arbitrary patterns on the left of a let, and it will destructure the given value.

Assignment: =

The left-hand side of an = must designate a mutable slot. The right-hand side indicates what to put in that slot.

Transferring things around by reference: let, alt, and function invocations

Copying: copy