kripken · July 9, 2021 19:58 · fgmccabe · Jun 24, 2021 · kripken · Jun 24, 2021
diff --git a/.gitignore b/.gitignore
 *.wasm
 temp

diff --git a/README.markdown b/README.markdown
diff --git a/build.sh b/build.sh
 #!/bin/bash
 set -e
 echo "calling-linear"
 ~/Dev/binaryen/bin/wasm-opt calling-linear.wast -all -o calling-linear.wasm
 echo "returning-linear"
 ~/Dev/binaryen/bin/wasm-opt returning-linear.wast -all -o returning-linear.wasm
 echo "calling-gc"
 ~/Dev/binaryen/bin/wasm-opt calling-gc.wast -all -o calling-gc.wasm
 echo "returning-gc"
 ~/Dev/binaryen/bin/wasm-opt returning-gc.wast -all -o returning-gc.wasm
diff --git a/calling-gc.wast b/calling-gc.wast
 ;; (Comments that would be the same in this code and in calling-linear are
 ;; omitted - see them there.)
 (module
  (type $func (func (param (ref null data))))

  ;; A string of characters. For simplicity in this example, null-termination is
  ;; used in the array (and characters after that are ignored).
  (type $string (array (mut i8)))

  (import "js" "print-char" (func $print-char (param i32)))

  (import "returning" "start-conversation"
    (func $returning-start-conversation (result (ref null data))))

  (import "returning" "push-f64"
    (func $returning-push-f64 (param (ref null data)) (param f64)))

  (import "returning" "pop-char"
    (func $returning-pop-char (param (ref null data)) (result i32)))

  (import "returning" "end-conversation"
    (func $returning-end-conversation (param (ref null data))))

  (import "returning" "func" (func $returning-func (param (ref null data))))

  (func "main"
    ;; Note that we do not need a token at all for our half of the
    ;; conversation. We just need one for the other side. That is possible
    ;; because, unlike calling-linear, we don't have any special cleanup
    ;; to do at the end (thanks to GC).
    (local $returning-token (ref null data))

    ;; Comparing to calling-linear, note how here we use a GC string while
    ;; there we used one in linear memory.
    (local $string (ref null $string))

    ;; Print "G " to identify ourselves as using GC.
    (call $print-char (i32.const 71))
    (call $print-char (i32.const 32))

    (local.set $returning-token
      (call $returning-start-conversation)
    )

    (local.set $string
      (call $bridge-conversation
        (ref.func $returning-func)
        (f64.const 1.0)
        (local.get $returning-token)
      )
    )

    (call $print-string
      (local.get $string)
    )

    (call $returning-end-conversation
      (local.get $returning-token)
    )
  )

  (func $bridge-conversation
    (param $func (ref $func))
    (param $param f64)
    (param $returning-token (ref null data))
    (result (ref null $string))

    (local $char i32)

    ;; The string we build up from received characters.
    (local $string (ref null $string))
    ;; The next position to write a character to.
    (local $string-index i32)

    (call $returning-push-f64
      (local.get $returning-token)
      (local.get $param))

    (call_ref
      (local.get $returning-token)
      (local.get $func)
    )

    ;; Allocate a string to write to.
    (local.set $string
      (array.new_default_with_rtt $string
        ;; To avoid handling string appending, just allocate a huge string for
        ;; example purposes.
        (i32.const 1000)
        (rtt.canon $string)
      )
    )

    (loop $loop
      (local.set $char
        (call $returning-pop-char
          (local.get $returning-token)
        )
      )

      (array.set $string
        (local.get $string)
        (local.get $string-index)
        (local.get $char)
      )

      (if
        (local.get $char)
        (block
          (local.set $string-index
            (i32.add
              (local.get $string-index)
              (i32.const 1)
            )
          )
          (br $loop)
        )
      )
    )

    (local.get $string)
  )

  (func $print-string (param $string (ref null $string))
    (local $char i32)
    (local $index i32)
    (loop $loop
      (local.set $char
        (array.get $string
          (local.get $string)
          (local.get $index)
        )
      )

      (call $print-char (local.get $char))

      (if
        (local.get $char)
        (block
          (local.set $index
            (i32.add
              (local.get $index)
              (i32.const 1)))
          (br $loop)
        )
      )
    )
  )
 )
diff --git a/calling-linear.wast b/calling-linear.wast
 (module
  ;; The type of the function we will call. This takes a conversation token,
  ;; which is a (ref null data). Note that it does not include the actual
  ;; parameters or return values, because their types may not agree on both
  ;; sides. That is, we can't write "i32" for the type of a string here -
  ;; that would work for C but not a GC language. (Note, however, that if
  ;; we added relevant types to wasm then we could use them here.)
  ;;
  ;; Note that we could use (ref data) here, that is, we do not need to
  ;; actually allow null references. However, in the current state of wasm
  ;; GC there are no non-nullable locals, so we'd need to clutter the code
  ;; with ref.as_non_null instructions.
  (type $func (func (param (ref null data))))

  ;; The information necessary during a conversation. Specifically, we need
  ;; to store the string that we allocate and write to on our side, so that
  ;; we can free it later.
  (type $conversation (struct
    ;; The allocated string that contains the characters returned to us from
    ;; the call to the other module.
    (field $string (mut i32))
  ))

  (memory 1 1)

  ;; A JS import so that we can do some printing to show that things work.
  (import "js" "print-char" (func $print-char (param i32)))

  ;; Start a conversation with the "returning" module. Returns a token that
  ;; identifies the (half of the) conversation on that side.
  (import "returning" "start-conversation"
    (func $returning-start-conversation (result (ref null data))))

  ;; Push an f64 parameter in a conversation. The function takes a conversation
  ;; token (as more than one conversation may be occurring), and then the parameter.
  ;; In this example, f64 is assumed to be a type that is universally agreed
  ;; upon, and so we just use that type both here and on the other side.
  (import "returning" "push-f64"
    (func $returning-push-f64 (param (ref null data)) (param f64)))

  ;; Get the next character from the output string. 0 indicates the end. (Another
  ;; approach could send the string length.)
  (import "returning" "pop-char"
    (func $returning-pop-char (param (ref null data)) (result i32)))

  ;; End the conversation on the other module. This does any necessary cleanup
  ;; there (which only that module understands and knows about).
  (import "returning" "end-conversation"
    (func $returning-end-conversation (param (ref null data))))

  ;; The function in the returning module that we will call. This has the
  ;; type $func which was declared earlier, see notes there about its signature.
  (import "returning" "func" (func $returning-func (param (ref null data))))

  ;; Internal state for malloc. (Ignore this.)
  (global $malloc-state (mut i32) (i32.const 0))

  ;; A function that will do a call to another module, using the bridging
  ;; approach.
  (func "main"
    ;; We will store the conversation tokens in locals, and the string
    ;; result as well.
    ;; Note that we use the specific type of our conversation token,
    ;; $conversation, because we understand it, while we use the
    ;; generic (ref null data) for the other side's conversation token,
    ;; since we know nothing about their internal implementation details.
    (local $token (ref null $conversation))
    (local $returning-token (ref null data))
    (local $string i32)

    ;; Print "L " to identify ourselves as using linear memory.
    (call $print-char (i32.const 76))
    (call $print-char (i32.const 32))

    ;; Start the two sides of the conversation, getting tokens for each.
    (local.set $token
      (call $start-conversation)
    )
    (local.set $returning-token
      (call $returning-start-conversation)
    )

    ;; Do the actual call. Instead of calling $returning-func directly,
    ;; we call the "glue" method $bridge-conversation. We call that method
    ;; in an almost normal way, passing it an f64 and receiving an i32 that
    ;; represents a string, that is, we use the types that make sense in
    ;; the language this module was compiled from (linear memory); we leave
    ;; all the interfacing to $bridge-conversation. The only difference in
    ;; our call to that method compared to a normal direct call is that we
    ;; also send it the conversation tokens, and a reference to the function
    ;; we wish to call.
    (local.set $string
      (call $bridge-conversation
        (ref.func $returning-func)
        (f64.const 1.0)
        (local.get $token)
        (local.get $returning-token)
      )
    )

    ;; Use the string result. It's just a normal linear memory string.
    (call $print-string
      (local.get $string)
    )

    ;; End the conversation after we are done with it.
    (call $returning-end-conversation
      (local.get $returning-token)
    )
    (call $end-conversation
      (local.get $token)
    )
  )

  (func $start-conversation (result (ref null $conversation))
    ;; Allocate a new conversation info structure.
    (struct.new_default_with_rtt $conversation
      (rtt.canon $conversation)
    )
  )

  (func $end-conversation (param $token (ref null $conversation))
    ;; Free the allocated string. Note that this works even if we did not
    ;; end up allocating a string, as free(0) is a no-op (both in C and in the
    ;; simple malloc/free here), so this actually already supports conditional
    ;; allocation in that sense. More generally, we could store a little state
    ;; on the $conversation data structure "things to free" that would be
    ;; added to only if we allocated, etc. (However, in this simple example,
    ;; we always allocate.)
    (call $free
      (struct.get $conversation $string
        (local.get $token)
      )
    )
  )

  ;; The bridging logic.
  ;;
  ;; Note that this method could also be in a third module "in between"
  ;; this module and the returning module. There are tradeoffs both
  ;; ways.
  ;;
  ;; Note also that this method could be factored into smaller pieces, like
  ;; a separate function to convert a string, etc.
  (func $bridge-conversation
    ;; The function to be called. We could instead bake in the call target in
    ;; this function, but using a reference shows how a single bridging method
    ;; could be used for multiple target functions with the same signature.
    (param $func (ref $func))
    ;; The f64 parameter to the function being called.
    (param $param f64)
    ;; The conversation token in this module.
    (param $token (ref null $conversation))
    ;; The conversation token in the returning module.
    (param $returning-token (ref null data))
    ;; The resulting string (which is usable while the conversation is ongoing).
    (result i32)

    (local $char i32)
    (local $string-ptr i32)
    (local $string-pos i32)

    ;; Push the parameter.
    (call $returning-push-f64
      (local.get $returning-token)
      (local.get $param)
    )

    ;; Call the target function. By giving it the proper conversation token,
    ;; it can read the parameter we sent, and set the result where we can
    ;; get to it later.
    (call_ref
      (local.get $returning-token)
      (local.get $func)
    )

    ;; Allocate room for our string. For simplicity we allocate a big-enough
    ;; region here in a simple way (actual production code would be more
    ;; clever obviously).
    (struct.set $conversation $string
      (local.get $token)
      ;; string-ptr is the pointer to the string. string-pos is the
      ;; current position in the string as we write to it, which will
      ;; be incremented as we go in the loop below.
      (local.tee $string-ptr
        (local.tee $string-pos
          (call $malloc
            (i32.const 1000)
          )
        )
      )
    )

    ;; Pop resulting characters and append them to our string.
    (loop $loop
      ;; Get a character.
      (local.set $char
        ;; See notes in README.markdown about performance.
        (call $returning-pop-char
          (local.get $returning-token)
        )
      )

      ;; Write it
      (i32.store8
        (local.get $string-pos)
        (local.get $char)
      )

      ;; If it is not the null-terminator, then increment and loop.
      (if
        (local.get $char)
        (block
          (local.set $string-pos
            (i32.add
              (local.get $string-pos)
              (i32.const 1)
            )
          )
          (br $loop)
        )
      )
    )

    ;; Return the linear-memory string.
    (local.get $string-ptr)
  )

  ;; Print a linear memory string, character by character. (You can ignore
  ;; this.)
  (func $print-string (param $x i32)
    (local $char i32)
    (loop $loop
      ;; Load the next character.
      (local.set $char
        (i32.load8_u
          (local.get $x)
        )
      )

      ;; Print it.
      (call $print-char (local.get $char))

      ;; If it is not the null-terminator, then increment and loop.
      (if
        (local.get $char)
        (block
          (local.set $x
            (i32.add
              (local.get $x)
              (i32.const 1)
            )
          )
          (br $loop)
        )
      )
    )
  )

  (func $malloc (param $size i32) (result i32)
    ;; Do a trivial bump allocation in this example code. In production we would
    ;; have a real malloc here. (You can ignore this, and $free.)
    (global.set $malloc-state
      (i32.add
        (global.get $malloc-state)
        (local.get $size)
      )
    )
    (i32.sub
      (global.get $malloc-state)
      (local.get $size)
    )
  )

  (func $free (param $ptr i32)
    ;; Do nothing. In production we would have a real malloc here.
  )
 )
diff --git a/reference.txt b/reference.txt
 testing calling-linear.wasm => returning-linear.wasm
 L little
 testing calling-linear.wasm => returning-gc.wasm
 L few
 testing calling-gc.wasm => returning-linear.wasm
 G little
 testing calling-gc.wasm => returning-gc.wasm
 G few
diff --git a/returning-gc.wast b/returning-gc.wast
 ;; (Comments that would be the same in this code and in calling-linear or
 ;; calling-gc are omitted - see them there.)
 (module
  (type $string (array (mut i8)))

  (type $conversation (struct
    ;; The f64 parameter.
    (field $param (mut f64))
    ;; The string output.
    (field $string (mut (ref null $string)))
    ;; The current position in the string output, as it is read character-by-
    ;; character.
    (field $string-index (mut i32))
  ))

  (func "start-conversation" (result (ref null data))
    (struct.new_default_with_rtt $conversation
      (rtt.canon $conversation)
    )
  )

  (func "end-conversation" (param $token (ref null data))
  )

  (func "push-f64" (param $token (ref null data)) (param $param f64)
    (struct.set $conversation $param
      (ref.cast
        (local.get $token)
        (rtt.canon $conversation)
      )
      (local.get $param)
    )
  )

  (func "pop-char" (param $token (ref null data)) (result i32)
    (local $conversation (ref null $conversation))
    (local $char i32)
    (local.set $conversation
      (ref.cast
        (local.get $token)
        (rtt.canon $conversation)
      )
    )
    ;; Read the next char.
    (local.set $char
      (array.get_u $string
        (struct.get $conversation $string
          (local.get $conversation)
        )
        (struct.get $conversation $string-index
          (local.get $conversation)
        )
      )
    )
    ;; Increment the string index.
    (struct.set $conversation $string-index
      (local.get $conversation)
      (i32.add
        (struct.get $conversation $string-index
          (local.get $conversation)
        )
        (i32.const 1)
      )
    )
    (local.get $char)
  )

  (func "func" (param $token (ref null data))
    (local $conversation (ref null $conversation))
    (local $string (ref null $string))
    (local.set $conversation
      (ref.cast
        (local.get $token)
        (rtt.canon $conversation)
      )
    )
    ;; Pick which string to return based on the input.
    (if
      ;; Check if the input is less than 2.
      (f64.le
        (struct.get $conversation $param
          (local.get $conversation)
        )
        (f64.const 2)
      )
      (block
        ;; Write out "few\0".
        (local.set $string
          (array.new_default_with_rtt $string
            (i32.const 4)
            (rtt.canon $string)
          )
        )
        (array.set $string
          (local.get $string)
          (i32.const 0)
          (i32.const 102)
        )
        (array.set $string
          (local.get $string)
          (i32.const 1)
          (i32.const 101)
        )
        (array.set $string
          (local.get $string)
          (i32.const 2)
          (i32.const 119)
        )
        (array.set $string
          (local.get $string)
          (i32.const 3)
          (i32.const 0)
        )
      )
      (block
        ;; Write out "many\0".
        (local.set $string
          (array.new_default_with_rtt $string
            (i32.const 5)
            (rtt.canon $string)
          )
        )
        (array.set $string
          (local.get $string)
          (i32.const 0)
          (i32.const 109)
        )
        (array.set $string
          (local.get $string)
          (i32.const 1)
          (i32.const 97)
        )
        (array.set $string
          (local.get $string)
          (i32.const 2)
          (i32.const 110)
        )
        (array.set $string
          (local.get $string)
          (i32.const 3)
          (i32.const 121)
        )
        (array.set $string
          (local.get $string)
          (i32.const 4)
          (i32.const 0)
        )
      )
    )
    ;; Set the string in the conversation.
    (struct.set $conversation $string
      (local.get $conversation)
      (local.get $string)
    )
  )
 )
diff --git a/returning-linear.wast b/returning-linear.wast
 ;; (Comments that would be the same in this code and in calling-linear are
 ;; omitted - see them there.)
 (module
  ;; The information necessary during a conversation.
  (type $conversation (struct
    ;; The f64 parameter.
    (field $param (mut f64))
    ;; The string output. This is incremented as we read it character-by-
    ;; character.
    (field $string (mut i32))
  ))

  (memory 1 1)

  ;; We will return one of these two strings. (A more elaborate demo could also
  ;; allocate or even conditionally allocate here; conditional allocation would
  ;; require us to store state on the conversation to know whether to free or
  ;; not, etc.)
  (data (i32.const 10) "little")
  (data (i32.const 20) "much")

  (func "start-conversation" (result (ref null data))
    (struct.new_default_with_rtt $conversation
      (rtt.canon $conversation)
    )
  )

  (func "push-f64" (param $token (ref null data)) (param $param f64)
    (struct.set $conversation $param
      ;; Note that after inlining these casts could be removed using simple
      ;; optimizations (which Binaryen already does, for example).
      (ref.cast
        (local.get $token)
        (rtt.canon $conversation)
      )
      (local.get $param)
    )
  )

  (func "pop-char" (param $token (ref null data)) (result i32)
    (local $conversation (ref null $conversation))
    (local $string i32)
    (local $char i32)
    (local.set $conversation
      (ref.cast
        (local.get $token)
        (rtt.canon $conversation)
      )
    )
    (local.set $string
      (struct.get $conversation $string
        (local.get $conversation)
      )
    )
    ;; Read the next char.
    (local.set $char
      (i32.load8_u
        (local.get $string)
      )
    )
    ;; Increment the pointer to the string.
    (struct.set $conversation $string
      (local.get $conversation)
      (i32.add
        (local.get $string)
        (i32.const 1)
      )
    )
    (local.get $char)
  )

  (func "end-conversation" (param $token (ref null data))
    ;; In this example we have nothing to do, as the strings are static.
    ;; However, if we allocated a string in "func" then we could note that fact
    ;; on the conversation info struct, and free it here, etc.
  )

  ;; The function that is called from the calling module. It does something with
  ;; the f64 it is given, then returns a string.
  ;;
  ;; Note that this code contains both the "business logic" of input processing
  ;; and the code to read things from the conversation. The business logic - the
  ;; if statement - could be in a separate function, if a toolchain prefers to
  ;; emit things that way.
  (func "func" (param $token (ref null data))
    (local $conversation (ref null $conversation))
    (local.set $conversation
      (ref.cast
        (local.get $token)
        (rtt.canon $conversation)
      )
    )
    ;; Pick which string to return based on the input.
    (struct.set $conversation $string
      (local.get $conversation)
      (if (result i32)
        ;; Check if the input is less than 2.
        (f64.le
          (struct.get $conversation $param
            (local.get $conversation)
          )
          (f64.const 2)
        )
        (i32.const 10) ;; "little"
        (i32.const 20) ;; "much"
      )
    )
  )
 )
diff --git a/test.js b/test.js
 //
 // Test script for d8. This requires new d8 with GC support. Run it with
 // something like:
 //
 //  d8 --experimental-wasm-gc test.js
 //

 const JSSupport = {
  _buffer: [],

  "print-char": function(char) {
    if (char) {
      JSSupport._buffer.push(char);
    } else {
      var string = '';
      for (let char of JSSupport._buffer) {
        string += String.fromCharCode(char);
      }
      console.log(string);
      JSSupport._buffer.length = 0;
    }
  }
 };

 // Receive the names of two modules, one that does the call and one that
 // returns a value when it is called, and test them.
 function testModules(callingName, returningName) {
  console.log('testing', callingName, '=>', returningName);

  // Create the modules.
  let callingModule = new WebAssembly.Module(readbuffer(callingName));
  let returningModule = new WebAssembly.Module(readbuffer(returningName));

  // Create the instances. The calling module receives the returning one's
  // exports.
  let returningInstance = new WebAssembly.Instance(returningModule, {});
  let callingInstance = new WebAssembly.Instance(callingModule, {
    js: JSSupport,
    returning: returningInstance.exports
  });

  // Run!
  callingInstance.exports.main();
 }

 // Test all combinations of the modules, in order to show that they are all
 // independent of each other. That is, the calling module does not need to be
 // modified at all even if we swap the returning module from linear memory to
 // GC.
 for (let calling of ['linear', 'gc']) {
  for (let returning of ['linear', 'gc']) {
    testModules('calling-' + calling + '.wasm',
                'returning-' + returning + '.wasm');
  }
 }
diff --git a/test.sh b/test.sh
 #!/bin/bash
 set -e
 echo "Building..."
 ./build.sh
 echo
 echo "Running..."
 d8 --experimental-wasm-gc test.js  &> temp
 diff reference.txt temp
 echo
 echo "Success!"
Name	Role	Language
calling-linear	Calls a module	Linear memory
calling-gc	Calls a module	GC
returning-linear	Is called, returns a value	Linear memory
returning-gc	Is called, returns a value	GC
	#!/bin/bash
	set -e
	echo "calling-linear"
	~/Dev/binaryen/bin/wasm-opt calling-linear.wast -all -o calling-linear.wasm
	echo "returning-linear"
	~/Dev/binaryen/bin/wasm-opt returning-linear.wast -all -o returning-linear.wasm
	echo "calling-gc"
	~/Dev/binaryen/bin/wasm-opt calling-gc.wast -all -o calling-gc.wasm
	echo "returning-gc"
	~/Dev/binaryen/bin/wasm-opt returning-gc.wast -all -o returning-gc.wasm
	;; (Comments that would be the same in this code and in calling-linear are
	;; omitted - see them there.)
	(module
	(type $func (func (param (ref null data))))

	;; A string of characters. For simplicity in this example, null-termination is
	;; used in the array (and characters after that are ignored).
	(type $string (array (mut i8)))

	(import "js" "print-char" (func $print-char (param i32)))

	(import "returning" "start-conversation"
	(func $returning-start-conversation (result (ref null data))))

	(import "returning" "push-f64"
	(func $returning-push-f64 (param (ref null data)) (param f64)))

	(import "returning" "pop-char"
	(func $returning-pop-char (param (ref null data)) (result i32)))

	(import "returning" "end-conversation"
	(func $returning-end-conversation (param (ref null data))))

	(import "returning" "func" (func $returning-func (param (ref null data))))

	(func "main"
	;; Note that we do not need a token at all for our half of the
	;; conversation. We just need one for the other side. That is possible
	;; because, unlike calling-linear, we don't have any special cleanup
	;; to do at the end (thanks to GC).
	(local $returning-token (ref null data))

	;; Comparing to calling-linear, note how here we use a GC string while
	;; there we used one in linear memory.
	(local $string (ref null $string))

	;; Print "G " to identify ourselves as using GC.
	(call $print-char (i32.const 71))
	(call $print-char (i32.const 32))

	(local.set $returning-token
	(call $returning-start-conversation)
	)

	(local.set $string
	(call $bridge-conversation
	(ref.func $returning-func)
	(f64.const 1.0)
	(local.get $returning-token)
	)
	)

	(call $print-string
	(local.get $string)
	)

	(call $returning-end-conversation
	(local.get $returning-token)
	)
	)

	(func $bridge-conversation
	(param $func (ref $func))
	(param $param f64)
	(param $returning-token (ref null data))
	(result (ref null $string))

	(local $char i32)

	;; The string we build up from received characters.
	(local $string (ref null $string))
	;; The next position to write a character to.
	(local $string-index i32)

	(call $returning-push-f64
	(local.get $returning-token)
	(local.get $param))

	(call_ref
	(local.get $returning-token)
	(local.get $func)
	)

	;; Allocate a string to write to.
	(local.set $string
	(array.new_default_with_rtt $string
	;; To avoid handling string appending, just allocate a huge string for
	;; example purposes.
	(i32.const 1000)
	(rtt.canon $string)
	)
	)

	(loop $loop
	(local.set $char
	(call $returning-pop-char
	(local.get $returning-token)
	)
	)

	(array.set $string
	(local.get $string)
	(local.get $string-index)
	(local.get $char)
	)

	(if
	(local.get $char)
	(block
	(local.set $string-index
	(i32.add
	(local.get $string-index)
	(i32.const 1)
	)
	)
	(br $loop)
	)
	)
	)

	(local.get $string)
	)

	(func $print-string (param $string (ref null $string))
	(local $char i32)
	(local $index i32)
	(loop $loop
	(local.set $char
	(array.get $string
	(local.get $string)
	(local.get $index)
	)
	)

	(call $print-char (local.get $char))

	(if
	(local.get $char)
	(block
	(local.set $index
	(i32.add
	(local.get $index)
	(i32.const 1)))
	(br $loop)
	)
	)
	)
	)
	)
	(module
	;; The type of the function we will call. This takes a conversation token,
	;; which is a (ref null data). Note that it does not include the actual
	;; parameters or return values, because their types may not agree on both
	;; sides. That is, we can't write "i32" for the type of a string here -
	;; that would work for C but not a GC language. (Note, however, that if
	;; we added relevant types to wasm then we could use them here.)
	;;
	;; Note that we could use (ref data) here, that is, we do not need to
	;; actually allow null references. However, in the current state of wasm
	;; GC there are no non-nullable locals, so we'd need to clutter the code
	;; with ref.as_non_null instructions.
	(type $func (func (param (ref null data))))

	;; The information necessary during a conversation. Specifically, we need
	;; to store the string that we allocate and write to on our side, so that
	;; we can free it later.
	(type $conversation (struct
	;; The allocated string that contains the characters returned to us from
	;; the call to the other module.
	(field $string (mut i32))
	))

	(memory 1 1)

	;; A JS import so that we can do some printing to show that things work.
	(import "js" "print-char" (func $print-char (param i32)))

	;; Start a conversation with the "returning" module. Returns a token that
	;; identifies the (half of the) conversation on that side.
	(import "returning" "start-conversation"
	(func $returning-start-conversation (result (ref null data))))

	;; Push an f64 parameter in a conversation. The function takes a conversation
	;; token (as more than one conversation may be occurring), and then the parameter.
	;; In this example, f64 is assumed to be a type that is universally agreed
	;; upon, and so we just use that type both here and on the other side.
	(import "returning" "push-f64"
	(func $returning-push-f64 (param (ref null data)) (param f64)))

	;; Get the next character from the output string. 0 indicates the end. (Another
	;; approach could send the string length.)
	(import "returning" "pop-char"
	(func $returning-pop-char (param (ref null data)) (result i32)))

	;; End the conversation on the other module. This does any necessary cleanup
	;; there (which only that module understands and knows about).
	(import "returning" "end-conversation"
	(func $returning-end-conversation (param (ref null data))))

	;; The function in the returning module that we will call. This has the
	;; type $func which was declared earlier, see notes there about its signature.
	(import "returning" "func" (func $returning-func (param (ref null data))))

	;; Internal state for malloc. (Ignore this.)
	(global $malloc-state (mut i32) (i32.const 0))

	;; A function that will do a call to another module, using the bridging
	;; approach.
	(func "main"
	;; We will store the conversation tokens in locals, and the string
	;; result as well.
	;; Note that we use the specific type of our conversation token,
	;; $conversation, because we understand it, while we use the
	;; generic (ref null data) for the other side's conversation token,
	;; since we know nothing about their internal implementation details.
	(local $token (ref null $conversation))
	(local $returning-token (ref null data))
	(local $string i32)

	;; Print "L " to identify ourselves as using linear memory.
	(call $print-char (i32.const 76))
	(call $print-char (i32.const 32))

	;; Start the two sides of the conversation, getting tokens for each.
	(local.set $token
	(call $start-conversation)
	)
	(local.set $returning-token
	(call $returning-start-conversation)
	)

	;; Do the actual call. Instead of calling $returning-func directly,
	;; we call the "glue" method $bridge-conversation. We call that method
	;; in an almost normal way, passing it an f64 and receiving an i32 that
	;; represents a string, that is, we use the types that make sense in
	;; the language this module was compiled from (linear memory); we leave
	;; all the interfacing to $bridge-conversation. The only difference in
	;; our call to that method compared to a normal direct call is that we
	;; also send it the conversation tokens, and a reference to the function
	;; we wish to call.
	(local.set $string
	(call $bridge-conversation
	(ref.func $returning-func)
	(f64.const 1.0)
	(local.get $token)
	(local.get $returning-token)
	)
	)

	;; Use the string result. It's just a normal linear memory string.
	(call $print-string
	(local.get $string)
	)

	;; End the conversation after we are done with it.
	(call $returning-end-conversation
	(local.get $returning-token)
	)
	(call $end-conversation
	(local.get $token)
	)
	)

	(func $start-conversation (result (ref null $conversation))
	;; Allocate a new conversation info structure.
	(struct.new_default_with_rtt $conversation
	(rtt.canon $conversation)
	)
	)

	(func $end-conversation (param $token (ref null $conversation))
	;; Free the allocated string. Note that this works even if we did not
	;; end up allocating a string, as free(0) is a no-op (both in C and in the
	;; simple malloc/free here), so this actually already supports conditional
	;; allocation in that sense. More generally, we could store a little state
	;; on the $conversation data structure "things to free" that would be
	;; added to only if we allocated, etc. (However, in this simple example,
	;; we always allocate.)
	(call $free
	(struct.get $conversation $string
	(local.get $token)
	)
	)
	)

	;; The bridging logic.
	;;
	;; Note that this method could also be in a third module "in between"
	;; this module and the returning module. There are tradeoffs both
	;; ways.
	;;
	;; Note also that this method could be factored into smaller pieces, like
	;; a separate function to convert a string, etc.
	(func $bridge-conversation
	;; The function to be called. We could instead bake in the call target in
	;; this function, but using a reference shows how a single bridging method
	;; could be used for multiple target functions with the same signature.
	(param $func (ref $func))
	;; The f64 parameter to the function being called.
	(param $param f64)
	;; The conversation token in this module.
	(param $token (ref null $conversation))
	;; The conversation token in the returning module.
	(param $returning-token (ref null data))
	;; The resulting string (which is usable while the conversation is ongoing).
	(result i32)

	(local $char i32)
	(local $string-ptr i32)
	(local $string-pos i32)

	;; Push the parameter.
	(call $returning-push-f64
	(local.get $returning-token)
	(local.get $param)
	)

	;; Call the target function. By giving it the proper conversation token,
	;; it can read the parameter we sent, and set the result where we can
	;; get to it later.
	(call_ref
	(local.get $returning-token)
	(local.get $func)
	)

	;; Allocate room for our string. For simplicity we allocate a big-enough
	;; region here in a simple way (actual production code would be more
	;; clever obviously).
	(struct.set $conversation $string
	(local.get $token)
	;; string-ptr is the pointer to the string. string-pos is the
	;; current position in the string as we write to it, which will
	;; be incremented as we go in the loop below.
	(local.tee $string-ptr
	(local.tee $string-pos
	(call $malloc
	(i32.const 1000)
	)
	)
	)
	)

	;; Pop resulting characters and append them to our string.
	(loop $loop
	;; Get a character.
	(local.set $char
	;; See notes in README.markdown about performance.
	(call $returning-pop-char
	(local.get $returning-token)
	)
	)

	;; Write it
	(i32.store8
	(local.get $string-pos)
	(local.get $char)
	)

	;; If it is not the null-terminator, then increment and loop.
	(if
	(local.get $char)
	(block
	(local.set $string-pos
	(i32.add
	(local.get $string-pos)
	(i32.const 1)
	)
	)
	(br $loop)
	)
	)
	)

	;; Return the linear-memory string.
	(local.get $string-ptr)
	)

	;; Print a linear memory string, character by character. (You can ignore
	;; this.)
	(func $print-string (param $x i32)
	(local $char i32)
	(loop $loop
	;; Load the next character.
	(local.set $char
	(i32.load8_u
	(local.get $x)
	)
	)

	;; Print it.
	(call $print-char (local.get $char))

	;; If it is not the null-terminator, then increment and loop.
	(if
	(local.get $char)
	(block
	(local.set $x
	(i32.add
	(local.get $x)
	(i32.const 1)
	)
	)
	(br $loop)
	)
	)
	)
	)

	(func $malloc (param $size i32) (result i32)
	;; Do a trivial bump allocation in this example code. In production we would
	;; have a real malloc here. (You can ignore this, and $free.)
	(global.set $malloc-state
	(i32.add
	(global.get $malloc-state)
	(local.get $size)
	)
	)
	(i32.sub
	(global.get $malloc-state)
	(local.get $size)
	)
	)

	(func $free (param $ptr i32)
	;; Do nothing. In production we would have a real malloc here.
	)
	)
	testing calling-linear.wasm => returning-linear.wasm
	L little
	testing calling-linear.wasm => returning-gc.wasm
	L few
	testing calling-gc.wasm => returning-linear.wasm
	G little
	testing calling-gc.wasm => returning-gc.wasm
	G few
	;; (Comments that would be the same in this code and in calling-linear or
	;; calling-gc are omitted - see them there.)
	(module
	(type $string (array (mut i8)))

	(type $conversation (struct
	;; The f64 parameter.
	(field $param (mut f64))
	;; The string output.
	(field $string (mut (ref null $string)))
	;; The current position in the string output, as it is read character-by-
	;; character.
	(field $string-index (mut i32))
	))

	(func "start-conversation" (result (ref null data))
	(struct.new_default_with_rtt $conversation
	(rtt.canon $conversation)
	)
	)

	(func "end-conversation" (param $token (ref null data))
	)

	(func "push-f64" (param $token (ref null data)) (param $param f64)
	(struct.set $conversation $param
	(ref.cast
	(local.get $token)
	(rtt.canon $conversation)
	)
	(local.get $param)
	)
	)

	(func "pop-char" (param $token (ref null data)) (result i32)
	(local $conversation (ref null $conversation))
	(local $char i32)
	(local.set $conversation
	(ref.cast
	(local.get $token)
	(rtt.canon $conversation)
	)
	)
	;; Read the next char.
	(local.set $char
	(array.get_u $string
	(struct.get $conversation $string
	(local.get $conversation)
	)
	(struct.get $conversation $string-index
	(local.get $conversation)
	)
	)
	)
	;; Increment the string index.
	(struct.set $conversation $string-index
	(local.get $conversation)
	(i32.add
	(struct.get $conversation $string-index
	(local.get $conversation)
	)
	(i32.const 1)
	)
	)
	(local.get $char)
	)

	(func "func" (param $token (ref null data))
	(local $conversation (ref null $conversation))
	(local $string (ref null $string))
	(local.set $conversation
	(ref.cast
	(local.get $token)
	(rtt.canon $conversation)
	)
	)
	;; Pick which string to return based on the input.
	(if
	;; Check if the input is less than 2.
	(f64.le
	(struct.get $conversation $param
	(local.get $conversation)
	)
	(f64.const 2)
	)
	(block
	;; Write out "few\0".
	(local.set $string
	(array.new_default_with_rtt $string
	(i32.const 4)
	(rtt.canon $string)
	)
	)
	(array.set $string
	(local.get $string)
	(i32.const 0)
	(i32.const 102)
	)
	(array.set $string
	(local.get $string)
	(i32.const 1)
	(i32.const 101)
	)
	(array.set $string
	(local.get $string)
	(i32.const 2)
	(i32.const 119)
	)
	(array.set $string
	(local.get $string)
	(i32.const 3)
	(i32.const 0)
	)
	)
	(block
	;; Write out "many\0".
	(local.set $string
	(array.new_default_with_rtt $string
	(i32.const 5)
	(rtt.canon $string)
	)
	)
	(array.set $string
	(local.get $string)
	(i32.const 0)
	(i32.const 109)
	)
	(array.set $string
	(local.get $string)
	(i32.const 1)
	(i32.const 97)
	)
	(array.set $string
	(local.get $string)
	(i32.const 2)
	(i32.const 110)
	)
	(array.set $string
	(local.get $string)
	(i32.const 3)
	(i32.const 121)
	)
	(array.set $string
	(local.get $string)
	(i32.const 4)
	(i32.const 0)
	)
	)
	)
	;; Set the string in the conversation.
	(struct.set $conversation $string
	(local.get $conversation)
	(local.get $string)
	)
	)
	)
	//
	// Test script for d8. This requires new d8 with GC support. Run it with
	// something like:
	//
	// d8 --experimental-wasm-gc test.js
	//

	const JSSupport = {
	_buffer: [],

	"print-char": function(char) {
	if (char) {
	JSSupport._buffer.push(char);
	} else {
	var string = '';
	for (let char of JSSupport._buffer) {
	string += String.fromCharCode(char);
	}
	console.log(string);
	JSSupport._buffer.length = 0;
	}
	}
	};

	// Receive the names of two modules, one that does the call and one that
	// returns a value when it is called, and test them.
	function testModules(callingName, returningName) {
	console.log('testing', callingName, '=>', returningName);

	// Create the modules.
	let callingModule = new WebAssembly.Module(readbuffer(callingName));
	let returningModule = new WebAssembly.Module(readbuffer(returningName));

	// Create the instances. The calling module receives the returning one's
	// exports.
	let returningInstance = new WebAssembly.Instance(returningModule, {});
	let callingInstance = new WebAssembly.Instance(callingModule, {
	js: JSSupport,
	returning: returningInstance.exports
	});

	// Run!
	callingInstance.exports.main();
	}

	// Test all combinations of the modules, in order to show that they are all
	// independent of each other. That is, the calling module does not need to be
	// modified at all even if we swap the returning module from linear memory to
	// GC.
	for (let calling of ['linear', 'gc']) {
	for (let returning of ['linear', 'gc']) {
	testModules('calling-' + calling + '.wasm',
	'returning-' + returning + '.wasm');
	}
	}
	#!/bin/bash
	set -e
	echo "Building..."
	./build.sh
	echo
	echo "Running..."
	d8 --experimental-wasm-gc test.js &> temp
	diff reference.txt temp
	echo
	echo "Success!"