diff --git a/design/mvp/Binary.md b/design/mvp/Binary.md index 2192ca53..9480d689 100644 --- a/design/mvp/Binary.md +++ b/design/mvp/Binary.md @@ -280,6 +280,7 @@ canonopt ::= 0x00 => string-encod | 0x03 m: => (memory m) | 0x04 f: => (realloc f) | 0x05 f: => (post-return f) + | 0x06 => reference-type πŸ“‘ ``` Notes: * The second `0x00` byte in `canon` stands for the `func` sort and thus the diff --git a/design/mvp/Explainer.md b/design/mvp/Explainer.md index c97e5f0f..40940b7d 100644 --- a/design/mvp/Explainer.md +++ b/design/mvp/Explainer.md @@ -44,6 +44,7 @@ implemented, considered stable and included in a future milestone: * πŸͺ™: value imports/exports and component-level start function * πŸͺΊ: nested namespaces and packages in import/export names * 🧡: threading built-ins +* πŸ“‘: reference types ([gc] proposal integration) (Based on the previous [scoping and layering] proposal to the WebAssembly CG, this repo merges and supersedes the [module-linking] and [interface-types] @@ -598,6 +599,7 @@ sets of abstract values: | `own` | a unique, opaque address of a resource that will be destroyed when this value is dropped | | `borrow` | an opaque address of a resource that must be dropped before the current export call returns | + How these abstract values are produced and consumed from Core WebAssembly values and linear memory is configured by the component via *canonical lifting and lowering definitions*, which are introduced [below](#canonical-definitions). @@ -1168,11 +1170,14 @@ canonopt ::= string-encoding=utf8 | (memory ) | (realloc ) | (post-return ) + | reference-type πŸ“‘ ``` While the production `externdesc` accepts any `sort`, the validation rules for `canon lift` would only allow the `func` sort. In the future, other sorts may be added (viz., types), hence the explicit sort. +##### `string-encoding` options + The `string-encoding` option specifies the encoding the Canonical ABI will use for the `string` type. The `latin1+utf16` encoding captures a common string encoding across Java, JavaScript and .NET VMs and allows a dynamic choice @@ -1182,6 +1187,8 @@ Point range) or UTF-16 (which can express all Code Points, but uses either default is UTF-8. It is a validation error to include more than one `string-encoding` option. +##### `memory` options + The `(memory ...)` option specifies the memory that the Canonical ABI will use to load and store values. If the Canonical ABI needs to load or store, validation requires this option to be present (there is no default). @@ -1199,6 +1206,43 @@ The Canonical ABI will use `realloc` both to allocate (passing `0` for the first two parameters) and reallocate. If the Canonical ABI needs `realloc`, validation requires this option to be present (there is no default). +##### `reference-type` options + +πŸ“‘ `reference-type` does not take effect by default. When this option +is turned on, Canonical ABI will be required to use reference types to pass +parameters. This option conflicts with `memory` and `realloc` and cannot +exist at the same time. + +πŸ“‘ When `reference-type` is enabled, the parameter type will change as follows: + +| wit type | wasm w/o `reference-type` | wasm w/ `reference-type` | +| :------------------- | :-------------------------- | :-------------------------------- | +| `bool` | `(i32,)` | `(i32,)` | +| `char` | `(i32,)` | `(i32,)` | +| `u8` | `(i32,)` | `(i32,)` | +| `u16` | `(i32,)` | `(i32,)` | +| `u32` | `(i32,)` | `(i32,)` | +| `u64` | `(i32,)` | `(i32,)` | +| `resource` | `(ptr: i32)` | `(ref extern,)` | +| `list` | `(ptr: i32, len: i32)` | `(ref array (mut $t),)` | +| `record { a, b }` | `(a: A, b: B)` (flatten) | `(ref struct $record,)` | +| `tuple`(inβ©½16) | `(a: A, b: B)` (flatten) | `(a: A, b: B)` (flatten) | +| `tuple`(out>1) | `(ptr: i32)` | `(ref struct (mut $a) (mut $b),)` | + +πŸ“‘ For variant types, they will be unpacked into two parts: enumeration and data. + +| wit type | wasm w/o `reference-type` | wasm w/ `reference-type` | +| :---------------------- | :-------------------------- | :----------------------- | +| `option` (heap type) | `(i32, [A_SIZE])` | `(i32, (ref null eq))` | +| `none` (heap type) | `(0, [FILL_ZEROES])` | `(1, null)` | +| `(some A)` (heap type) | `(1, [A_SIZE])` | `(0, ref $a)` | +| `result` | `(i32, [MAX_VARIANT_SIZE])` | `(i32, (ref null eq))` | +| `(ok A)` | `(0, [A_SIZE])` | `(0, ref $a)` | +| `(err B)` | `(1, [B_SIZE])` | `(1, ref $b)` | +| `variant` | `(i32, [MAX_VARIANT_SIZE])` | `(i32, (ref null eq))` | + +##### `post-return` options + The `(post-return ...)` option may only be present in `canon lift` and specifies a core function to be called with the original return values after they have finished being read, allowing memory to be deallocated and diff --git a/design/mvp/FutureFeatures.md b/design/mvp/FutureFeatures.md index 4b94f3b7..68ff8e6e 100644 --- a/design/mvp/FutureFeatures.md +++ b/design/mvp/FutureFeatures.md @@ -38,6 +38,15 @@ to and from the statically-compiled host implementation language). See [`list.lift_canon` and `list.lower_canon`] for more details. +## Mutability constraints on reference types πŸ“‘ + +Mutability constraints are a complex issue, especially in oop languages. For +example, whether array is internally mutable determines whether some operations +can accept specific subtypes. There are no constraints in the current MVP +version, which may lead to unexpected semantic damage. This can only be +guaranteed by the language compiler for the time being, and it is not +cross-language safe. + ## Shared-some-things linking via "adapter modules" The original [Interface Types proposal] and the re-layered [Module Linking