v0.4.0
Ownership · Lesson 11.5

Non-copyable types

Source
Mark a plain-data type #NoCopy, so that it can only be moved.
You'll need: Destructor, Move

A hotel key stands for a room. The key itself is plain data — a room number — so the compiler would happily copy it, and then two guests could each check out of the same room. For a type like this the automatic copy is wrong, and Rux lets the type turn it off.

Once copying is off, the only way to hand a key on is to move it. One key, one owner, one checkout — and the compiler checks all three.

Turning copying off

The attribute #NoCopy on the declaration says "this type has no copy":

#NoCopy
struct RoomKey {
    room: int32;
}

That is all. RoomKey keeps its one int32 field and needs no extend block; it simply stops being copyable.

A type with a destructor needs no attribute: it owns something, so it is already move-only. #NoCopy is for plain data that must still never be duplicated, such as a handle that something else releases. Its sibling #NoMove goes further and keeps a value in the place where it was built.

Moving instead

From then on every use that would copy a key is an error, and the diagnostic shows the move to write instead:

let spare = key;
error: cannot copy 'RoomKey', which prohibits copying
  note: a named value used by value in initialization position is copied, and only plain data copies
  help: write 'move key' to transfer it

With move, the key changes hands and key is finished:

let friend = move key;
PrintLine("    friend holds key {}", friend.room);

Passing by value is a copy too, so an argument needs move as well. CheckOut takes ownership of the key, so after the call nobody holds it any more:

func CheckOut(key: RoomKey) {
    PrintLine("    checking out of room {}", key.room);
    PrintLine("    key {} handed back", key.room);
}
CheckOut(move friend);
PrintLine("    done");

Fresh keys and borrowed keys

Two things still work without move. A value made on the spot has no old owner, so CheckIn returns its new key with a plain return, and Main takes it with a plain =:

func CheckIn(room: int32) -> RoomKey {
    PrintLine("    key {} issued", room);
    return RoomKey { room: room };
}
let key = CheckIn(12);

And a borrow is not a copy. A function that only needs to look at a key takes &RoomKey, and the caller keeps the key.

flowchart LR
    k(["`key: RoomKey`<br/>`#NoCopy`"]) -- "`let spare = key`" --> x["`error: cannot copy`<br/>`'RoomKey'`"]
    k -- "`let friend = move key`" --> f["`friend` owns the key<br/>`key` is finished"]
    k -- "`Peek(key)` with `key: &RoomKey`" --> b["borrowed for the call<br/>`key` still owns it"]

Everywhere a copy would happen

Every by-value use of a named key needs move. The compiler's note names the place in each error — initialization, argument, return or assignment position:

WhereRefusedWritten with a move
A bindinglet spare = key;let spare = move key;
An argumentCheckOut(key)CheckOut(move key)
A returnreturn key;return move key;
A struct fieldBooking { key: key }Booking { key: move key }
An assignmentkey = other;key = move other;

The prohibition also spreads outwards. A struct with a RoomKey field cannot be copied either — copying it would copy the key — so the compiler treats the whole struct as move-only, and let copy = booking; is refused with cannot copy 'Booking', which prohibits copying.

The program

The whole lesson is one package in the Examples repository. Its comments explain every step.

Src/Main.rux
// A hotel key stands for a room. The key itself is plain data, a room number, so the compiler
// would happily copy it, and then two guests could each check out of the same room. For a type
// like this the automatic copy is wrong, and Rux lets the type turn it off.
//
// The attribute `#NoCopy` on the declaration says "this type has no copy":
//
//     #NoCopy
//     struct RoomKey { room: int32; }
//
// From then on every use that would copy a key is an error, and the only way to hand one on is
// to move it with `move`. One key, one owner, one checkout.
//
// A type with a destructor needs no attribute: it owns resources, so it is already move-only, as
// Destructor showed. `#NoCopy` is for plain data that must still never be duplicated, such as a
// handle that something else releases. (Its sibling `#NoMove` goes further and keeps a value
// where it was built.)
import Io::PrintLine;

#NoCopy
struct RoomKey {
    room: int32;
}

func CheckIn(room: int32) -> RoomKey {
    PrintLine("    key {} issued", room);
    return RoomKey { room: room };
}

// Takes ownership of the key, so after this call nobody holds it any more.
func CheckOut(key: RoomKey) {
    PrintLine("    checking out of room {}", key.room);
    PrintLine("    key {} handed back", key.room);
}

func Main() -> int {
    PrintLine("check in:");
    let key = CheckIn(12);

    // A copy is refused, and the diagnostic shows the move to write instead:
    //
    //     let spare = key;
    //
    // error: cannot copy 'RoomKey', which prohibits copying
    //   note: a named value used by value in initialization position is copied, and only plain
    //         data copies
    //   help: write 'move key' to transfer it

    PrintLine("give the key to a friend:");
    let friend = move key;
    PrintLine("    friend holds key {}", friend.room);

    // Passing by value is a copy too, so the argument needs `move` as well. Without it:
    //
    //     error: cannot copy 'RoomKey', which prohibits copying
    //       help: write 'move friend' to transfer it
    PrintLine("check out:");
    CheckOut(move friend);
    PrintLine("    done");
    return 0;
}

Run it

cd Examples/Ownership/NoCopy
rux run
check in:
    key 12 issued
give the key to a friend:
    friend holds key 12
check out:
    checking out of room 12
    key 12 handed back
    done

Common mistakes

Try it yourself

  1. Write func Peek(key: &RoomKey) that prints the room number, and call it twice on key before giving it to the friend. Why does Peek need no move?
  2. Write func Spare(room: int32) -> RoomKey that stores a new key in a let before returning it. Which return does it need?
  3. Make two var keys and replace the first with first = move second;. Can second still be read afterwards?
  4. Declare struct Booking { guest: char8[..]; key: RoomKey; }, build one, and try to copy it with =. What does the error say about Booking?

Learn more