Scenarios

proposals/interface-types/Explainer.md

@@ -6,8 +6,9 @@ committing to a single memory representation or sharing scheme. Interface types
 can only be used in the interfaces of modules and can only be produced or
 consumed by declarative **interface adapters**.
 
-The proposal is semantically layered on top of the WebAssembly [core spec],
-adding only the ability to adapt the imports and exports of a WebAssembly
+The proposal is semantically layered on top of the WebAssembly [core spec]
+(extended with the [multi-value] and [reference types] proposals), and
+adds only the ability to adapt the imports and exports of a WebAssembly
 module at points which are already host-defined behavior. All adaptations are
 specified in a [custom section] and this feature can be polyfilled using the
 [JS API].
@@ -168,8 +169,9 @@ other types and concepts are introduced.
 
 ### Export returning string (statically allocated)
 
-Let's start with a WebAssembly module that you can write today that returns a
-string that is stored at a fixed location in linear memory:
+Let's start with a WebAssembly module that you can write today (with 
+[multi-value]) that returns a string that is stored at a fixed location in
+linear memory:
 
 ```wasm
 (module
@@ -689,6 +691,7 @@ leverage existing and planned reference types ([`anyref`], [function references]
 [Type Import]: https://github.com/WebAssembly/proposal-type-imports/blob/master/proposals/type-imports/Overview.md#imports
 [GC]: https://github.com/WebAssembly/gc/blob/master/proposals/gc/Overview.md
 
+[Multi-value]: https://github.com/WebAssembly/multi-value/blob/master/proposals/multi-value/Overview.md
 [Block Validation]: https://webassembly.github.io/multi-value/core/valid/instructions.html#valid-block
 [Select Validation]: https://webassembly.github.io/reference-types/core/valid/instructions.html#valid-select
 

proposals/interface-types/working-notes/WorkingNotes.md

@@ -0,0 +1,23 @@
+# Working Notes
+
+The purpose of this directory is to hold notes about the current design of the
+Interface Types proposal. These notes are intended as analogous to the
+[WebAssembly design repo](https://github.com/WebAssembly/design/), as a
+less-formal way of designing components of the proposal. Documents should
+reflect our current consensus, but the ideas don't need to be fully fleshed out.
+These documents should inform the final spec.
+
+Sample topics:
+* How we should handle Wasm exceptions
+* How engines might need to optimize combinations of adapters
+* What is necessary for MVP, and what can be deferred
+
+In general, we should try to match the conventions that are already established,
+but when inventing some new topic, just making up syntax/instructions is the
+right way to go.
+
+### Q: Why not add these to the Explainer?
+These aren't necessarily things that the explainer needs to spell out. If the
+purpose of the explainer is to convey the information to a reader from scratch,
+the nuances of a given design detail is likely to be distracting detail. It is
+likely that some subsets will wind up in the explainer over time.

proposals/interface-types/working-notes/record.md

@@ -0,0 +1,73 @@
+
+
+### Records
+
+Records are collections of named and typed fields. Records can be defined in as
+Interface Types; for example this definition encodes a familiar notion of a
+credit card:
+
+```wat
+(@interface datatype @cc 
+  (record "cc"
+    (ccNo u64)
+    (name string)
+    (expires (record
+      (mon u8)
+      (year u16)
+      )
+    )
+    (ccv u16)
+  )
+)
+```
+
+Lifting and lowering a record involves lifting/lowering the individual fields of
+the record and then 'packing' or 'unpacking' the record as an ordered
+sub-sequence of elements on the stack.
+
+For example, the sequence:
+
+```wat
+...
+local.get $ccNo
+i64-to-u64
+local.get $name
+local.get $name.len
+memory-to-string
+i8.local.get $mon
+i8_to_u8
+i16.local.get $year
+i16_to_u16
+pack @(record (mon u8) (year u16))
+local.get $ccv
+pack @cc.cc
+...
+```
+creates a credit card information record from various local variables.
+
+Lowering a record is complimentary, involving an `unpack` operator; together
+with individual lowering operators for the fields:
+
+```wat
+...
+unpack @cc.cc $ccNo $name $expires $ccv
+  local.get $ccNo
+  u64-to-i64
+  local.get $name
+  string-to-memory "malloc"
+  local.get $expires
+  unpack @(record (mon u8) (year u16)) $mon $year
+    local.get $mon
+    u8-to-i32
+    local.get $year
+    u16-to-i32
+  end
+  local.get $ccv
+  u16-to-i32
+end
+```
+
+The result of this unpacking is to leave the fields of the record on the
+stack. If the intention were to store the record in memory then this code could
+be augmented with memory store instructions.
+

proposals/interface-types/working-notes/scenarios/cc.md

@@ -0,0 +1,251 @@
+# Pay by Credit Card
+
+In order to process a payment with a credit card, various items of information
+are required: credit card details, amount, merchant bank, and so on. This
+example illustrates the use of nominal types and record types in adapter code.
+
+>Note that we have substantially simplified the scenario in order to construct
+>an illustrative example.
+
+The signature of `payWithCard` as an interface type is:
+
+```
+cc ::= cc{
+  ccNo : u64;
+  name : string;
+  expires : {
+    mon : u8;
+    year : u16
+  }
+  ccv : u16
+}
+payWithCard:(card:cc, amount:s64, session:resource<connection>) => boolean
+```
+
+## Export
+
+In order to handle the incoming information, a record value must be passed --
+including a `string` component -- and a `session` that denotes the bank
+connection must be paired with an existing connection resource. The connection
+information is realized as an `eqref` (an `anyref` that supports equality).
+
+In this scenario, we are assuming that the credit card information is passed by
+value (each field in a separate argument) to the internal implementation of the
+export, and passed by reference to the import.
+
+```
+(@interface datatype @cc 
+  (record "cc"
+    (ccNo u64)
+    (name string)
+    (expires (record
+      (mon u8)
+      (year u16)
+      )
+    )
+    (ccv u16)
+  )
+)
+
+(@interface typealias @connection eqref)
+
+(memory (export $memx) 1)
+
+(func $payWithCard_ (export ("" "payWithCard_"))
+  (param i64 i32 i32 i32 i32 i32 eqref) (result i32)
+
+(@interface func (export "payWithCard")
+  (param $card @cc)
+  (param $session (resource @connection))
+  (result boolean)
+
+  local.get $card
+  field.get #cc.ccNo   ;; access ccNo
+  u64-to-i64
+
+  local.get $card
+  field.get #cc.name
+  string-to-memory $mem1 "malloc"
+
+  local.get $card
+  field.get #cc.expires.mon
+
+  local.get $card
+  field.get #cc.expires.year
+
+  local.get $card
+  field.get #cc.ccv
+
+  local.get $session
+  resource-to-eqref @connection
+  call $payWithCard_
+  i32-to-enum boolean
+)
+
+(func (export "malloc")
+  (param $sze i32) (result i32)
+  ...
+)
+```
+
+## Import
+
+In this example, we assume that the credit details are passed to the import by
+reference; i.e., the actual argument representing the credit card information is
+a pointer to a block of memory.
+
+```
+(func $payWithCard_ (import ("" "payWithCard_"))
+  (param i32 eqref) (result i32)
+
+(@interface func $payWithCard (import "" "payWithCard")
+  (param @cc (resource @connection))
+  (result boolean))
+
+(@interface implement (import "" "payWithCard_")
+  (param $cc i32)
+  (param $conn eqref)
+  (result i32)
+
+  local.get $cc
+  i64.load {offset #cc.ccNo}
+  i64-to-u64
+
+  local.get $cc
+  i32.load {offset #cc.name.ptr}
+
+  local.get $cc
+  i32.load {offset #cc.name.len}
+  memory-to-string "memi"
+
+  local.get $cc
+  i16.load_u {offset #cc.expires.mon}
+
+  local.get $cc
+  i16.load_u {offset #cc.expires.year}
+
+  create (record (mon u16) (year u16))
+
+  local.get $cc
+  i16.load_u {offset #cc.ccv}
+
+  create @cc
+
+  local.get $conn
+  eqref-to-resource @connection
+
+  call $payWithCard
+  enum-to-i32 boolean
+)
+```
+
+## Adapter
+
+Combining the import, exports and distributing the arguments, renaming `cc` for
+clarity, we initially get:
+
+```
+(@adapter implement (import "" "payWithCard_")
+  (param $cc i32)
+  (param $conn eqref)
+  (result i32)
+
+  local.get $cc
+  i64.load {offset #cc.ccNo}
+  i64-to-u64
+
+  local.get $cc
+  i32.load {offset #cc.name.ptr}
+
+  local.get $cc
+  i32.load {offset #cc.name.len}
+  memory-to-string "memi"
+
+  local.get $cc
+  i16.load_u {offset #cc.expires.mon}
+
+  local.get $cc
+  i16.load_u {offset #cc.expires.year}
+
+  create (record (mon u16) (year u16))
+
+  local.get $cc
+  i16.load_u {offset #cc.ccv}
+
+  create @cc
+
+  local.get $conn
+  eqref-to-resource @connection
+
+  let $session (resource @connection)
+  let $card @cc
+
+  local.get $card
+  field.get #cc.ccNo   ;; access ccNo
+  u64-to-i64
+
+  local.get $card
+  field.get #cc.name
+  string-to-memory $mem1 "malloc"
+
+  local.get $card
+  field.get #cc.expires.mon
+  u16-to-i32
+
+  local.get $card
+  field.get #cc.expires.year
+  u16-to-i32
+
+  local.get $card
+  field.get #cc.ccv
+  u16-to-i32
+
+  local.get $session
+
+  resource-to-eqref @connection
+  call $payWithCard_
+  i32-to-enum boolean
+  end
+  end
+  enum-to-i32 boolean
+)
+```
+
+With some assumptions (such as no aliasing, no writing to locals, no
+re-entrancy), we can propagate and inline the definitions of intermediates. This
+amounts to 'regular' inlining where we recurse into records and treat the fields
+of the record in an analogous fashion to arguments to the call.
+
+```
+(@adapter implement (import "" "payWithCard_")
+  (param $cc i32)
+  (param $conn eqref)
+  (result i32)
+
+  local.get $cc
+  i64.load {offset #cc.ccNo}
+
+  local.get $cc
+  i32.load {offset #cc.name.ptr}
+
+  local.get $cc
+  i32.load {offset #cc.name.len}
+  string.copy Mi:"mem2" Mx:"memx" "malloc"
+
+  local.get $cc
+  i16.load_u {offset #cc.expires.mon}
+
+  local.get $cc
+  i16.load_u {offset #cc.expires.year}
+
+  local.get $cc
+  i16.load_u {offset #cc.ccv}
+
+  local.get $conn
+  call $payWithCard_
+)
+```
+
+There would be different sequences for the adapter if the underlying ABI were different --
+for example, if structured data were passed as a pointer to a local copy for
+example.