Refactors API to ensure context propagation (#482)

This is an API breaking change that does a few things:

* Stop encouraging practice that can break context propagation:
  * Stops caching `context.Context` in `wazero.RuntimeConfig`
  * Stops caching `context.Context` in `api.Module`

* Fixes context propagation in function calls:
  * Changes `api.Function`'s arg0 from `api.Module` to `context.Context`
  * Adds `context.Context` parameter in instantiation (propagates to
    .start)

* Allows context propagation for heavy operations like compile:
  * Adds `context.Context` as the initial parameter of `CompileModule`

The design we had earlier was a good start, but this is the only way to
ensure coherence when users start correlating or tracing. While adding a
`context.Context` parameter may seem difficult, wazero is a low-level
library and WebAssembly is notoriously difficult to troubleshoot. In
other words, it will be easier to explain to users to pass (even nil) as
the context parameter vs try to figure out things without coherent
context.

Signed-off-by: Adrian Cole <adrian@tetrate.io>
This commit is contained in:
Crypt Keeper
2022-04-19 16:52:57 +08:00
committed by GitHub
parent 64d7379ad0
commit 45ccab589b
42 changed files with 592 additions and 607 deletions

View File

@@ -84,14 +84,6 @@ type Module interface {
// with the exitCode.
CloseWithExitCode(exitCode uint32) error
// Context returns any propagated context from the Runtime or a prior function call.
//
// The returned context is always non-nil; it defaults to context.Background.
Context() context.Context
// WithContext allows callers to override the propagated context, for example, to add values to it.
WithContext(ctx context.Context) Module
// Memory returns a memory defined in this module or nil if there are none wasn't.
Memory() Memory
@@ -129,23 +121,11 @@ type Function interface {
// encoded according to ResultTypes. An error is returned for any failure looking up or invoking the function
// including signature mismatch.
//
// If `m` is nil, it defaults to the module the function was defined in.
//
// To override context propagation, use Module.WithContext
// fn = m.ExportedFunction("fib")
// results, err := fn(m.WithContext(ctx), 5)
// --snip--
//
// To ensure context propagation in a host function body, pass the `ctx` parameter:
// hostFunction := func(m api.Module, offset, byteCount uint32) uint32 {
// fn = m.ExportedFunction("__read")
// results, err := fn(m, offset, byteCount)
// --snip--
//
// Note: when `ctx` is nil, it defaults to context.Background.
// Note: If Module.Close or Module.CloseWithExitCode were invoked during this call, the error returned may be a
// sys.ExitError. Interpreting this is specific to the module. For example, some "main" functions always call a
// function that exits.
Call(m Module, params ...uint64) ([]uint64, error)
Call(ctx context.Context, params ...uint64) ([]uint64, error)
}
// Global is a WebAssembly 1.0 (20191205) global exported from an instantiated module (wazero.Runtime InstantiateModule).