Rewrite explainer (again) to take into account new names, scope, and concepts

[lukewagner]

This PR updates the explainer to match the re-scoping presented in the June wasm f2f to include more than just Web IDL use cases. That presentation used "☃ Bindings" as a placeholder name, leaving us to find a name later. After much discussion, we've settled (over the last two video calls) on "Interface Types" along with an associated set of names that are described/diagramed in the "Overview" section of the explainer in this PR.

In addition to changing the naming and scope, this PR changes the way s/bindings/adapters/ are written to incorporate a bunch of ideas from the spec draft in #52. In particular s/bindings/adapters/ are generalized from two maps (applied to either side of an import/export) to just general functions which contain instructions (which may call imports/exports), in the same manner as core wasm (just with a different, much more limited, declarative instruction set; but otherwise structured and validated in the same way as wasm instructions).

Lastly, the explainer body is changed to be hopefully more concrete and understandable, using a sequence of code snippets to introduce concepts by example.

The explainer is intentionally incomplete (with an explicit TODO section listing additional planned sections), with the idea being to focus on just the simple (but important and representative) case of strings, get the explainer and spec aligned on just that, and then incrementally grow the two in lockstep thereafter.

[lukewagner]

@alexcrichton That's a good question. I was thinking that that might be the proper role of the spec document. Otherwise, the explainer just ends up duplicating the spec. Maybe the explainer could gain regularly-placed links into the spec though, "for more details", as each instruction is introduced?

@jgravelle-google Yes, good observation; and, as you observed earlier, you could similarly adapt returning a C-string to call a "write terminating null" export. These could be useful if interface adapters were added as some post-compilation step that didn't want to muck with the core module. Otherwise, I think it'd be a bit faster to inline these into the wasm before or after it called the import.

[jgravelle-google]

These could be useful if interface adapters were added as some post-compilation step that didn't want to muck with the core module

For example, say you wanted C code that was runnable both with Emscripten's glue (and deep knowledge of the wasm's ABI) and elsewhere. Given a void foo(char*);, Emscripten can know how to handle C strings, but Interface Types probably should not. It will be more portable for that code to not have to be wrapped with

#ifdef __EMSCRIPTEN__
#define FOO(x) (foo((x)))
#else
#define FOO(x) (foo((x), strlen((x)))
#endif

So to my taste, the less that user code needs to change to support Interface Types, the better. Secondary to that, if we can not change the generated code, that's a nice property to have.

Then I realized that all of this needs to be made exception safe and how there's probably some elegant, succinct RAII-like instruction that handles all these cases,

Yeah. My best idea so far is something like Nim's defer keyword, which semantically wraps the rest of the function in try/finally (and handles returns as well). In our case we'd need a signature? Or the assumption that it always copies one item off the stack?

But yeah that's figure-out-later-able.

[alexcrichton]

Maybe the explainer could gain regularly-placed links into the spec though, "for more details", as each instruction is introduced?

Sounds reasonable to me!

My personal experience with wasm proposals so far have been that I basically just exclusively read the explainer documents rather than the spec because I can't ever figure out where to look in the spec and I suspect this is coloring my opinion. In any case so long as it's somewhere that sounds like a good plan.

[lukewagner]

@alexcrichton Ah yes, I think you're not alone in that :) (I think this problem could be ameliorated if we had the ability to view the diff of the rendered HTML...) In our case here, the "spec" document we'll be working on won't be the core spec, but some new document (layered on top of the core) and so the entire document should be relevant, as it is the diff (from the empty file ;)

[fgmccabe]

It may not be in the explainer. However, 'types' does not normally include 'values'; which is why I was suggesting amendment rather than addition.

On Tue, Aug 20, 2019 at 11:15 AM Luke Wagner notifications@github.com wrote:

@lukewagner commented on this pull request.

In proposals/interface-types/Explainer.md https://github.com/WebAssembly/webidl-bindings/pull/59#discussion_r315833725 :

+* module: the basic unit of WebAssembly code whose structure is defined in

• the [core spec][Module Syntax] and which may only use value types in its
• functions +* module type: currently defined by the [core spec][Old Module Type] as a
• mapping from imports to exports. More recently, there is a [proposal][New Module Type]
• to generalize module types to include import/export names and have text
• format parse rules so that module types can be written separately from
• modules. +* known section: sections defined by the [core spec's binary format][Known Section]
• which collectively decode a module +* custom section: sections defined by the [core spec's binary format][Custom Section]
• whose contents are uninterpreted by the core spec but can be interpreted by
• other tools or specifications (including this proposal)

• +This proposal defines the following new high-level concepts: +* interface type: a new set of types that describe abstract, high-level values

Even though the list is introduced by saying it's introducing "new high-level concepts", what the list's real purpose is is just defining terms that are used throughout the rest of the document (hence the boldface). "Interface types" is used many times, and is symmetric to the existing term Value types https://webassembly.github.io/spec/core/syntax/types.html#value-types, so I think it has to stay: it's the term that refers to a specific set of types. As you've defined "Interface schema", the term basically covers the whole proposal (types, values, instructions, validation rules, execution rules) and I don't see where in the explainer this specific term would currently be used. But if you had a specific example, I'd be happy to discuss it.

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/WebAssembly/webidl-bindings/pull/59?email_source=notifications&email_token=AAQAXUCUHDKUFKWINNTAX7DQFQYEPA5CNFSM4INCKYXKYY3PNVWWK3TUL52HS4DFWFIHK3DMKJSXC5LFON2FEZLWNFSXPKTDN5WW2ZLOORPWSZGOCCEARSQ#discussion_r315833725, or mute the thread https://github.com/notifications/unsubscribe-auth/AAQAXUE7WFFLZM25QKLVR2DQFQYEPANCNFSM4INCKYXA .

-- Francis McCabe SWE

[lukewagner]

I don't follow; what are you proposing?

[fgmccabe]

Sorry. I meant two things really:

1. if you do not need the overall concept of a types+values schema in the explainer then feel free to omit.
2. Technically we need to have both types and values; and so it is not just types that will show up in the adapter functions.

On Tue, Aug 20, 2019 at 12:31 PM Luke Wagner notifications@github.com wrote:

I don't follow; what are you proposing?

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/WebAssembly/webidl-bindings/pull/59?email_source=notifications&email_token=AAQAXUEWTBRACM5QB7CTUR3QFRBA7A5CNFSM4INCKYXKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOD4XNBVI#issuecomment-523161813, or mute the thread https://github.com/notifications/unsubscribe-auth/AAQAXUGK2GM3MRWRBELJ6M3QFRBA7ANCNFSM4INCKYXA .

-- Francis McCabe SWE

[lukewagner]

@fgmccabe Great, thanks, and agreed. I looked at the definition of "adapter function" (in the Overview section) and indeed it mentions the use of interface types and adapter instructions, with adapter instructions being defined to manipulate interface values, so sound good?

[fgmccabe]

Yes-ish. I think you may get annoyed with the following (but I hope you will not): I was talking to Z (Zhi An Ng) about this naming story; and I think we may have a better name root: mediation. Values in the gap between modules are 'intermediate values', and the type system is a 'mediation type' system. The idea is that mediation is about bringing parties together; in this modules. We would still have adapters etc. Anyway, if that does not fly, 'interface values' is a bit dissonant because 'interface' normally refers to the specification of an API. I do think that it is worth emphasizing that these values are abstract and intrinsically not reified. Francis

On Tue, Aug 20, 2019 at 2:30 PM Luke Wagner notifications@github.com wrote:

@fgmccabe https://github.com/fgmccabe Great, thanks, and agreed. I looked at the definition of "adapter function" (in the Overview section) and indeed it mentions the use of interface types and adapter instructions, with adapter instructions being defined to manipulate interface values, so sound good?

— You are receiving this because you were mentioned.

Reply to this email directly, view it on GitHub https://github.com/WebAssembly/webidl-bindings/pull/59?email_source=notifications&email_token=AAQAXUDB76GORFPPOWGHG6DQFRPARA5CNFSM4INCKYXKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOD4XXCPY#issuecomment-523202879, or mute the thread https://github.com/notifications/unsubscribe-auth/AAQAXUDNZFG376VTXZYLG2LQFRPARANCNFSM4INCKYXA .

[lukewagner]

It's an interesting metaphor as you describe it, but both the definition and my experience with the word "mediation" mention mediation as the resolution of disputes, which seems to add a negative connotation to the whole proposal. (Naming is hard)

[jgravelle-google]

We could skip the middleman and just call this the "Naming Is Hard proposal", but then that abbreviates as NIH which is also already taken... because naming is still hard.

[lukewagner]

Alright, based on CG vote from earlier today and approvals, I'll merge this now and continue to iterate with future discussions and PRs.