Top-levels FunctionDefinition to allow access to all function metadata (#686)

This top-levels `api.FunctionDefinition` which was formerly
experimental, and also adds import metadata to it. Now, it holds all
metadata known at compile time.

Here are the public API visible changes:
* api.ExportedFunction - replaced with api.FunctionDefinition as it is
  usable for all types of functions.
* api.Function - `.ParamTypes/ResultTypes()` are replaced with
  `.Definition().
* api.FunctionDefinition - extracted from experimental and adds
  `.Import()` to get the any imported module and function name.
* experimental.FunctionDefinition - replaced with
  api.FunctionDefinition.
* experimental.FunctionListenerFactory - adds first arg of the
  instantiated module name, as it can be different than compiled.
* wazero.CompiledModule - Adds `.ImportedFunctions()` and changes result
  type of `.ExportedFunctions()` to api.FunctionDefinition.

Internally, logic to create function definition are consolidated between
host and wasm-defined functions, notably wasm.Module now includes
`.BuildFunctionDefinitions()` which reduces duplication in
wasm.ModuleInstance `.BuildFunctions()`,

This obviates #681 by deleting the `ExportedFunction` type which
overlaps with this information.

This fixes #637 as it includes more metadata including imports.

Signed-off-by: Adrian Cole <adrian@tetrate.io>
Co-authored-by: Takeshi Yoneda <takeshi@tetrate.io>

api/wasm.go

@@ -173,24 +173,71 @@ type Closer interface {
 	Close(context.Context) error
 }
 
-// ExportedFunction is a WebAssembly function exported in a module (wazero.CompiledModule).
+// FunctionDefinition is a WebAssembly function exported in a module (wazero.CompiledModule).
 //
 // See https://www.w3.org/TR/2019/REC-wasm-core-1-20191205/#exports%E2%91%A0
-type ExportedFunction interface {
-	// Name returns the name of this exported function which is unique across a module.
-	// Note: the empty name is allowed in the WebAssembly specification so returned "" is meaningful.
+type FunctionDefinition interface {
+	// ModuleName is the possibly empty name of the module defining this
+	// function.
+	//
+	// Note: This may be different from Module.Name, because a compiled module
+	// can be instantiated multiple times as different names.
+	ModuleName() string
+
+	// Index is the position in the module's function index namespace, imports
+	// first.
+	Index() uint32
+
+	// Name is the module-defined name of the function, which is not necessarily
+	// the same as its export name.
 	Name() string
 
-	// ParamTypes are the possibly empty sequence of value types accepted by a function with this signature.
+	// DebugName identifies this function based on its Index or Name in the
+	// module. This is used for errors and stack traces. Ex. "env.abort".
+	//
+	// When the function name is empty, a substitute name is generated by
+	// prefixing '$' to its position in the index namespace. Ex ".$0" is the
+	// first function (possibly imported) in an unnamed module.
+	//
+	// The format is dot-delimited module and function name, but there are no
+	// restrictions on the module and function name. This means either can be
+	// empty or include dots. Ex. "x.x.x" could mean module "x" and name "x.x",
+	// or it could mean module "x.x" and name "x".
+	//
+	// Note: This name is stable regardless of import or export. For example,
+	// if Import returns true, the value is still based on the Name or Index
+	// and not the imported function name.
+	DebugName() string
+
+	// Import returns true with the module and function name when this function
+	// is imported. Otherwise, it returns false.
+	//
+	// Note: Empty string is valid for both the imported module and function
+	// name in the WebAssembly specification.
+	Import() (moduleName, name string, isImport bool)
+
+	// ExportNames include all exported names for the given function.
+	//
+	// Note: The empty name is allowed in the WebAssembly specification, so ""
+	// is possible.
+	ExportNames() []string
+
+	// ParamTypes are the possibly empty sequence of value types accepted by a
+	// function with this signature.
 	//
 	// See ValueType documentation for encoding rules.
 	ParamTypes() []ValueType
 
-	// ResultTypes are the possibly empty sequence of value types returned by a function with this signature.
+	// ParamNames are index-correlated with ParamTypes or nil if not available
+	// for one or more parameters.
+	ParamNames() []string
+
+	// ResultTypes are the results of the function.
 	//
-	// When WebAssembly 1.0 (20191205), there can be at most one result: https://www.w3.org/TR/2019/REC-wasm-core-1-20191205/#result-types%E2%91%A0
+	// When WebAssembly 1.0 (20191205), there can be at most one result.
+	// See https://www.w3.org/TR/2019/REC-wasm-core-1-20191205/#result-types%E2%91%A0
 	//
-	// See ValueType documentation for decoding rules.
+	// See ValueType documentation for encoding rules.
 	ResultTypes() []ValueType
 }
 
@@ -198,17 +245,8 @@ type ExportedFunction interface {
 //
 // See https://www.w3.org/TR/2019/REC-wasm-core-1-20191205/#syntax-func
 type Function interface {
-	// ParamTypes are the possibly empty sequence of value types accepted by a function with this signature.
-	//
-	// See ValueType documentation for encoding rules.
-	ParamTypes() []ValueType
-
-	// ResultTypes are the possibly empty sequence of value types returned by a function with this signature.
-	//
-	// When WebAssembly 1.0 (20191205), there can be at most one result: https://www.w3.org/TR/2019/REC-wasm-core-1-20191205/#result-types%E2%91%A0
-	//
-	// See ValueType documentation for decoding rules.
-	ResultTypes() []ValueType
+	// Definition is metadata about this function from its defining module.
+	Definition() FunctionDefinition
 
 	// Call invokes the function with parameters encoded according to ParamTypes. Up to one result is returned,
 	// encoded according to ResultTypes. An error is returned for any failure looking up or invoking the function