Non-copyable types
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:
| Where | Refused | Written with a move |
|---|---|---|
| A binding | let spare = key; | let spare = move key; |
| An argument | CheckOut(key) | CheckOut(move key) |
| A return | return key; | return move key; |
| A struct field | Booking { key: key } | Booking { key: move key } |
| An assignment | key = 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.
// 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
- Write
func Peek(key: &RoomKey)that prints the room number, and call it twice onkeybefore giving it to the friend. Why doesPeekneed nomove? - Write
func Spare(room: int32) -> RoomKeythat stores a new key in aletbefore returning it. Whichreturndoes it need? - Make two
varkeys and replace the first withfirst = move second;. Cansecondstill be read afterwards? - Declare
struct Booking { guest: char8[..]; key: RoomKey; }, build one, and try to copy it with=. What does the error say aboutBooking?
Learn more
- Move —
movein all three places - Custom copy — copying a move-only type on purpose, with a
Clonemethod - Partial move — taking a struct of move-only fields apart
- Prohibiting copies in the Rux Reference