There is almost nothing to the FFI interface: Basically, the asm FFI can only have asm types, as you would expect. Then you can just call normal JS methods that were imported. So stuff like

    function asmFunc(import) {
      'use asm';

      var externFunc = import.externFunc;

      function asmFunc() {
        externFunc(123, -0.5);
      }

      return asmFunc;
    }

What extra info are you looking for?

> What extra info are you looking for?

Essentially, a complete executable example of a simple ASM.js program that involves a foreign function, including processing return values. (I imagine if it's this simple, then return values are handled using the same annotations as ASM.js functions?)

While I understand that specs don't necessarily have to have examples, I believe it would benefit the community to have one in the ASM.js spec.

Thanks for clarifying here, though! I now understand.

Yeah, ffis are just calls like any other, with the usual annotations and types on parameters and return values, etc. They just happen to be to functions on the outside of the asm module.

edit: btw, there is a full example here https://github.com/dherman/asm.js/#example

Ah, I wasn't aware there was an actual repo associated with ASM.js. The example doesn't show how you call into the module with `consoleDotLog` defined, though. I know that sounds like a triviality, but complete examples are really useful to cut through any possible ambiguity!

I would definitely lobby to get something smaller and concise into the spec under the "Putting it All Together" heading! You could modify the existing example in the spec to include an external function definition and call.

Follow-up question.

How does it deduce the return type of a foreign function? Can foreign functions return values?

Normally, ASM.js functions require an annotation on the return statement [0].

[0] http://asmjs.org/spec/latest/#return-type-annotations

FFI calls are just like normal calls: they need a coercion on them.

    i = ffiFunc() | 0; // returns an int
    d = +ffiFunc();    // returns a double

This is identical for FFI and non-FFI calls. A difference though is that asm functions have specific types (an asm function returns either nothing, an int, or a double). But an FFI is just any old JS function. So you could not write the above 2 lines together with an asm function, only an FFI can get an int one time and a double another time from the same function.

Understood. If `ffiFunc()` returns an empty array at a double call site, does ASM.js just accept it as `0`? (`+[]` is `0`). Or are there runtime checks that verify that the return value is a numeric type?

btw, I hope these questions make it clearer why I grumped a bit about the specification, and result in a more robust spec!

> The specification lacks examples, and seems to be very underspecified.

See "Putting It All Together" http://asmjs.org/spec/latest/

From that example, the list of return types from operators (section 8), and the graph of value types (section 2.1), it is simple to figure out, if not a little foreign at first.

The example doesn't use the FFI, though. And I understand the graph of value types and the restrictions that ASM.js imposes on ASM.js code, but there's no clear linkage between that and the FFI.

Some other FFIs require you to encode type information in some manner to uphold the guarantees of the language. It's not clear from scanning the specification if that is the case here, as the FFI is only briefly mentioned in passing.

Finally, ASM.js doesn't validate the return expression of external functions (it does for ASM.js code [0]). How does it deal with foreign functions that return values? What type does the return value take? Or does there need to be an annotation at the call site?

[0] http://asmjs.org/spec/latest/#return-type-annotations