rust/doc/tutorial/args.md

Argument passing

Rust datatypes are not trivial to copy (the way, for example, JavaScript values can be copied by simply taking one or two machine words and plunking them somewhere else). Shared boxes require reference count updates, big records, tags, or unique pointers require an arbitrary amount of data to be copied (plus updating the reference counts of shared boxes hanging off them).

For this reason, the default calling convention for Rust functions leaves ownership of the arguments with the caller. The caller guarantees that the arguments will outlive the call, the callee merely gets access to them.

Safe references

There is one catch with this approach: sometimes the compiler can not statically guarantee that the argument value at the caller side will survive to the end of the call. Another argument might indirectly refer to it and be used to overwrite it, or a closure might assign a new value to it.

Fortunately, Rust tasks are single-threaded worlds, which share no data with other tasks, and that most data is immutable. This allows most argument-passing situations to be proved safe without further difficulty.

Take the following program:

# fn get_really_big_record() -> int { 1 }
# fn myfunc(a: int) {}
fn main() {
    let x = get_really_big_record();
    myfunc(x);
}

Here we know for sure that no one else has access to the x variable in main, so we're good. But the call could also look like this:

# fn myfunc(a: int, b: block()) {}
# fn get_another_record() -> int { 1 }
# let x = 1;
myfunc(x, {|| x = get_another_record(); });

Now, if myfunc first calls its second argument and then accesses its first argument, it will see a different value from the one that was passed to it.

In such a case, the compiler will insert an implicit copy of x, except if x contains something mutable, in which case a copy would result in code that behaves differently. If copying x might be expensive (for example, if it holds a vector), the compiler will emit a warning.

There are even more tricky cases, in which the Rust compiler is forced to pessimistically assume a value will get mutated, even though it is not sure.

fn for_each(v: [mutable @int], iter: block(@int)) {
   for elt in v { iter(elt); }
}

For all this function knows, calling iter (which is a closure that might have access to the vector that's passed as v) could cause the elements in the vector to be mutated, with the effect that it can not guarantee that the boxes will live for the duration of the call. So it has to copy them. In this case, this will happen implicitly (bumping a reference count is considered cheap enough to not warn about it).

The copy operator

If the for_each function given above were to take a vector of {mutable a: int} instead of @int, it would not be able to implicitly copy, since if the iter function changes a copy of a mutable record, the changes won't be visible in the record itself. If we do want to allow copies there, we have to explicitly allow it with the copy operator:

type mutrec = {mutable x: int};
fn for_each(v: [mutable mutrec], iter: block(mutrec)) {
   for elt in v { iter(copy elt); }
}

Adding a copy operator is also the way to muffle warnings about implicit copies.

Other uses of safe references

Safe references are not only used for argument passing. When you destructure on a value in an alt expression, or loop over a vector with for, variables bound to the inside of the given data structure will use safe references, not copies. This means such references are very cheap, but you'll occasionally have to copy them to ensure safety.

let my_rec = {a: 4, b: [1, 2, 3]};
alt my_rec {
  {a, b} {
    log(info, b); // This is okay
    my_rec = {a: a + 1, b: b + [a]};
    log(info, b); // Here reference b has become invalid
  }
}

Argument passing styles

The fact that arguments are conceptually passed by safe reference does not mean all arguments are passed by pointer. Composite types like records and tags are passed by pointer, but single-word values, like integers and pointers, are simply passed by value. Most of the time, the programmer does not have to worry about this, as the compiler will simply pick the most efficient passing style. There is one exception, which will be described in the section on generics.

To explicitly set the passing-style for a parameter, you prefix the argument name with a sigil. There are two special passing styles that are often useful. The first is by-mutable-pointer, written with a single &:

fn vec_push(&v: [int], elt: int) {
    v += [elt];
}

This allows the function to mutate the value of the argument, in the caller's context. Clearly, you are only allowed to pass things that can actually be mutated to such a function.

Then there is the by-copy style, written +. This indicates that the function wants to take ownership of the argument value. If the caller does not use the argument after the call, it will be 'given' to the callee. Otherwise a copy will be made. This mode is mostly used for functions that construct data structures. The argument will end up being owned by the data structure, so if that can be done without a copy, that's a win.

type person = {name: str, address: str};
fn make_person(+name: str, +address: str) -> person {
    ret {name: name, address: address};
}