Destructor
A destructor is code that runs when a value's life ends. Nobody calls it. The compiler does, exactly once for every value that is still alive when its life ends — when its scope closes, when a function returns, or when = replaces it with a new value.
In real code a destructor gives back what the value was holding: a file, a network connection, a block of memory. Because the compiler calls it, it cannot be forgotten, and it cannot be called twice. Here the destructor only prints, so that you can watch exactly when it runs.
Writing a destructor
A destructor is written inside extend, named after the type with a leading ~, and borrows the dying value mutably:
struct Guest {
name: char8[..];
}
extend Guest {
func ~Guest(&var self) {
PrintLine(" {} leaves", self.name);
}
}
It takes no other parameters and returns nothing. The signature is fixed: func ~T(&var self), with the type's own name.
When a scope ends
The guest in Visit lives only as long as the call:
func Visit(name: char8[..]) {
let guest = Guest { name: name };
PrintLine(" {} visits", guest.name);
}
a short visit:
Ada visits
Ada leaves
back in Main
"Ada leaves" is printed by the destructor as Visit returns, before Main carries on. The same happens at the end of every block that owns a value — including each pass of a loop body.
When a value is replaced
Replacing a value ends the old one's life first:
var seat = Guest { name: "Bob" };
seat = Guest { name: "Cy" };
Bob leaves at the =. Cy now holds the seat and will leave later. Replacing one field of a struct works the same way: the old field value is destroyed, the rest of the struct is untouched.
When a value is moved
After a move, only the new owner is destroyed:
let host = Guest { name: "Dee" };
let moved = move host;
host gave its value away, so there is nothing left in host to destroy. Dee leaves once, at the end of Main, as moved.
Newest first
Values that end together are destroyed in reverse order of creation — newest first. At the end of Main, seat (holding Cy) was created before moved (holding Dee), so Dee leaves first:
flowchart LR
subgraph made["Created, in order"]
direction LR
c1["`seat` — Cy"] --> c2["`moved` — Dee"]
end
subgraph gone["Destroyed at the end of `Main`"]
direction LR
d1["Dee leaves"] --> d2["Cy leaves"]
end
made -- "reversed" --> goneThe order is not arbitrary. A value made later may depend on one made earlier — a reader that uses an open file, say — so it has to go first, while the thing it depends on is still there.
| What happens | Destructor runs |
|---|---|
| The owning scope ends | yes, newest value first |
= replaces the value | yes, on the old value, at the assignment |
The value is moved with move | not here — the new owner destroys it later |
| The value is copied | never — the copy is refused |
A destructor makes a type move-only
A copy of a guest would be a second guest, and it would leave too — "Dee leaves" printed twice for one person. For a guest that only prints, that is odd; for a value that frees memory or closes a file, it would free or close the same thing twice. So the compiler does not allow it: a type with a destructor owns something, and it is move-only. let twin = host; is refused:
error: cannot copy 'Guest', which owns resources
note: a named value used by value in initialization position is copied, and only plain data copies
help: write 'move host' to transfer it, or 'host.Clone()' to copy it
A guest is handed on with move, as the program does with host. The next lesson turns copying off for plain data that has no destructor, and Custom copy writes the Clone method that the help mentions.
The program
The whole lesson is one package in the Examples repository. Its comments explain every step.
// A destructor is code that runs when a value's life ends. It is written inside `extend`, named
// after the type with a leading `~`, and borrows the dying value mutably:
//
// func ~Guest(&var self) { ... }
//
// Nobody calls it. The compiler does, exactly once for every value that is still alive when its
// life ends: when its scope closes, when a function returns, or when `=` replaces it with a new
// value, whether it is a whole variable or one field of a struct. A value that was moved away is
// not destroyed where it was, because its new owner will destroy it later. Values that end
// together are destroyed in reverse order of creation, newest first.
//
// Here the destructor only prints, so its timing can be watched. In real code it gives back what
// the value was holding: a file, a connection, a block of memory. A copy would be a second guest
// that leaves too, so a type with a destructor is move-only: `let other = guest;` is refused with
// `cannot copy 'Guest', which owns resources`, and a guest is handed on with `move` instead.
import Io::PrintLine;
struct Guest {
name: char8[..];
}
extend Guest {
func ~Guest(&var self) {
PrintLine(" {} leaves", self.name);
}
}
// The guest lives only as long as this call.
func Visit(name: char8[..]) {
let guest = Guest { name: name };
PrintLine(" {} visits", guest.name);
}
func Main() -> int {
PrintLine("a short visit:");
Visit("Ada");
PrintLine(" back in Main");
// Replacing a value ends the old one's life first.
PrintLine("swapping the seat:");
var seat = Guest { name: "Bob" };
seat = Guest { name: "Cy" };
// After a move only the new owner is destroyed, so Dee leaves once, at the end.
PrintLine("moving:");
let host = Guest { name: "Dee" };
let moved = move host;
// `moved` was created after `seat`, so it is destroyed before it.
PrintLine("end of Main:");
return 0;
}
Run it
cd Examples/Ownership/Destructor
rux run
a short visit:
Ada visits
Ada leaves
back in Main
swapping the seat:
Bob leaves
moving:
end of Main:
Dee leaves
Cy leaves
Common mistakes
Try it yourself
- Create a guest inside a
forloop over0..3and print the pass number. When does each guest leave? - Add
let twin = host;before the move and read the error. Then change it tolet twin = move host;— what does the compiler now say aboutlet moved = move host;? - Declare
struct Table { number: int32; guest: Guest; }, make avartable, and assign a new guest to itsguestfield. Who leaves, and when?
Learn more
- Move — why a moved-from value is not destroyed
- Non-copyable types — move-only plain data, with no destructor
- Defer — cleanup that belongs to a piece of work rather than a value
- Destructors in the Rux Reference