Skip to content

Commit 80987f1

Browse files
committed
Update prose in CanonicalABI.md to match code
1 parent 994085a commit 80987f1

File tree

2 files changed

+13
-21
lines changed

2 files changed

+13
-21
lines changed

design/mvp/CanonicalABI.md

Lines changed: 12 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -370,13 +370,9 @@ handle to the `free` list for later recycling by `add` (above).
370370
return h
371371
```
372372
The `lend_count` guard ensures that no dangling borrows are created when
373-
destroying a resource. Because `transfer_or_drop` is used for cross-component
374-
transfer of `own` handles (via `lift_own` below), this `lend_count` guard
375-
ensures that when a component receives an `own`, it receives a unique reference
376-
to the resource and that there aren't any dangling borrows hanging around from
377-
the previous owner. The bookkeeping performed by `transfer_or_drop` for
378-
borrowed handles records the fulfillment of the obligation of the borrower to
379-
drop the handle before the end of the call.
373+
destroying a resource. The bookkeeping performed for borrowed handles records
374+
the fulfillment of the obligation of the borrower to drop the handle before the
375+
end of the call.
380376

381377
Finally, we can define `HandleTables` (plural) as simply a wrapper around
382378
a mutable mapping from `ResourceType` to `HandleTable`:
@@ -617,31 +613,28 @@ def unpack_flags_from_int(i, labels):
617613
return record
618614
```
619615

620-
Next, `own` handles are lifted removing the `OwnHandle` from the handle table
621-
and passing the underlying representation value as the lifted value. The other
622-
side will wrap this representation value in its own new `OwnHandle` in its on
623-
handle table.
616+
Next, `own` handles are lifted by extracting the `OwnHandle` from the current
617+
instance's handle table. This ensures that `own` handles are always uniquely
618+
referenced.
624619
```python
625620
def lift_own(cx, i, t):
626-
h = cx.inst.handles.transfer(i, t)
627-
return OwnHandle(h.rep, 0)
621+
return cx.inst.handles.transfer(i, t)
628622
```
629623
Note that `t` refers to an `own` type and thus `HandleTable.transfer` will, as
630624
shown above, ensure that the handle at index `i` is an `OwnHandle`.
631625

632-
Lastly, `borrow` handles are lifted by getting the handle out of the
633-
appropriate resource type's handle table.
626+
Lastly, `borrow` handles are lifted by handing out a `BorrowHandle` storing the
627+
same representation value as the lent handle. By incrementing `lend_count`,
628+
`lift_own` ensures that the lent handle will not be dropped before the end of
629+
the call (see the matching decrement in `canon_lower`) which transitively
630+
ensures that the lent resource will not be destroyed.
634631
```python
635632
def lift_borrow(cx, i, t):
636633
h = cx.inst.handles.get(i, t.rt)
637634
h.lend_count += 1
638635
cx.lenders.append(h)
639636
return BorrowHandle(h.rep, 0, None)
640637
```
641-
Thus, `borrow` lifting allows all handle types to be supplied for a `borrow`,
642-
as long as they have a matching resource type (`t.rt`). The lending handle is
643-
passed as the lifted value so that the receiver can increment and decrement
644-
its `lend_count`.
645638

646639

647640
### Storing

design/mvp/canonical-abi/definitions.py

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -576,8 +576,7 @@ def unpack_flags_from_int(i, labels):
576576
#
577577

578578
def lift_own(cx, i, t):
579-
h = cx.inst.handles.transfer(i, t)
580-
return OwnHandle(h.rep, 0)
579+
return cx.inst.handles.transfer(i, t)
581580

582581
#
583582

0 commit comments

Comments
 (0)