take in front of a field or an item
With one owner, an object could not hand on what one of its fields
holds. Reading the field only looks, and giving the value away would
leave nothing in the field. A list had pop(), but a field had
nothing. Since 0.8.0, take in front of a field or an item gives what
is there and leaves none in its place:
class Buffer {
bytes: list[int]
}
class Uart {
filling: Buffer or none
sent: int
function hand_on(self) -> Buffer or none {
return take self.filling
}
}
function send(buffer: take Buffer) -> int {
return len(buffer.bytes)
}
let uart = Uart(Buffer([1, 2, 3]), 0)
let full = uart.hand_on()
print(uart.filling is none)
if full is not none {
print(send(full))
}
let queue: list[Buffer or none] = [Buffer([4]), none, Buffer([5, 6])]
let last = take queue[2]
print(queue[2] is none, last is not none)
cargo run -- build --no-collector --memory hand.zeno
./hand
true
3
true true
memory: 12 blocks made (208 bytes), at most 152 bytes in use at once, no collector, 0 blocks left at the end
pool: 280 bytes taken, in a pool of 32768
text: at most 2 bytes in use at once, in a room of 1024
zeno run prints the same three lines, and so does every other build
and every target. The reasons for each choice are in 56.10 of
decisions.md. It is part 9.3 of
plan-9-14.md.
The rule
takein front of a field or an item gives what is there, and leavesnone.
The place must be one that may hold none, such as filling: Buffer
or none or a list[Buffer or none]. What is left is then something
its type already allows. What comes back may be none too, and is
tested as any such value is.
It means the same in every build. Where values are shared, it still
leaves none. So a program runs the same way under zeno run, in an
ordinary build and with no collector.
take goes in front of the whole place after it, as a minus does:
take slots[i].task, take make().task. It is a word that was
reserved already, so no program that built before means anything new.
What it cannot be in front of
A variable is not a place for it, since let b = a already gives a
away:
error: `take` goes in front of a field or an item, as in `take slot.task`, and leaves `none` there. `task` is a variable: `let other = task` already gives what it holds away
A place that cannot hold none is refused, and the message says how to
make it one. For a list, it also says that pop() takes the item out:
error: `take` leaves `none` in `id`, and `id` is written `int`, which does not allow `none`. If it may be empty, declare it as `id: int or none`
error: `take` leaves `none` in the place of the item, and the items of this list are written `Task`, which does not allow `none`. To take the item out, use `pop()`. To leave `none` in its place, make it a `list[Task or none]`
A value of a dict is not a place for it yet. A dict cannot hold a value
that may be none, so there would be nothing to leave.
With one owner
The value leaves the object or the list it was in. So the three guards
of pop() hold, in the same words:
- Only the owner may take it out. A function that was lent the object cannot know who else was lent the field:
error: only the owner can take out what is there: somebody else may have been lent it. Here `s` only looks at it
- Not while a loop walks the owner.
- Not on a line that has already looked at it. For example,
look(s.task, take s.task)is refused.look(take s.task, s.task)is fine, since the field holdsnoneby the time it is looked at.
A method may take out what its own object holds, as hand_on does
above. Whoever calls the method is then held to the rule in its place:
only the owner of uart may call uart.hand_on().
In the C
The value is read into a variable of its own, and none is written
where it was. Nothing is freed there. Whoever receives the value owns
it. If nobody does, as in print(take s.task), the statement owns it
and frees it when the line is over.
static z_Buffer *z_Uart_hand_on(z_Uart *z_self) {
z_Buffer *t5 = z_self->z_filling;
z_self->z_filling = NULL;
return t5;
}
Through LLVM it is a load and a store of null. The interpreter
does the same, and the VM has two new instructions for it, TakeField
and TakeIndex. The targets get two statements, one that keeps what is
there and one that stores none, so no target's runtime changed.
How it is tested
- The parser:
take_goes_in_front_of_a_field_or_an_itemchecks where it binds and both of its messages. - The checker:
take_leaves_none_where_a_value_waschecks: - the type in every kind of build;
- a place that cannot hold
none, and text; - the three guards;
- a method that takes out of its own object.
- Both compilers:
take_leaves_none_every_waybuildstools/targets/edge-take.zeno. It is built with no collector through C and LLVM, which give the same memory report with 0 blocks left. It is also built in the ordinary and firmware builds of both. The program has: - a scheduler that hands its task on;
- fields and items holding an object, text or a number that may be
none; - a list of a fixed length;
- a thousand rounds;
- a value that nobody receives.
The same test checks that a bad index stops the program at the
take, at the same line and column, in each build of C.
- The targets run the same program.
Things to try
- Build
hand.zenowith--no-collectorand openhand.c. Findz_Uart_hand_on. Why is nothing freed there, and who frees the buffer in the end? - Write
let full = uart.fillinginstead of callinghand_on. Read the message. What would go wrong if it were allowed? - Take
or noneofffilling. Which line is refused now, and why cantakenot be used on that field any more? - Write
function steal(u: Uart) -> Buffer or none { return u.hand_on() }and build it with--no-collector. Which word does the message want, and where? - Write
print(take uart.filling, uart.filling), then the two the other way round. Why is one refused and the other not? - Use a
list[Buffer or none]as a ring of buffers. Hand each one on withtake ring[i], and put a new one in its place. Build it with--memory. How many blocks are left at the end?
This page is docs/take.md in the language repository.