sys

Documentation

Overview

Package sys includes constants and types used by both public and internal APIs.

Index

• Constants
• type ClockResolution
• type ExitError
  • func NewExitError(exitCode uint32) *ExitError
  • func (e *ExitError) Error() string
  • func (e *ExitError) ExitCode() uint32
  • func (e *ExitError) Is(err error) bool
• type Nanosleep
• type Nanotime
• type Osyield
• type Walltime

Constants

const (
	// ExitCodeContextCanceled corresponds to context.Canceled and returned by ExitError.ExitCode in that case.
	ExitCodeContextCanceled uint32 = 0xffffffff
	// ExitCodeDeadlineExceeded corresponds to context.DeadlineExceeded and returned by ExitError.ExitCode in that case.
	ExitCodeDeadlineExceeded uint32 = 0xefffffff
)

These two special exit codes are reserved by wazero for context Cancel and Timeout integrations. The assumption here is that well-behaving Wasm programs won't use these two exit codes.

Types

type ClockResolution

type ClockResolution uint32

ClockResolution is a positive granularity of clock precision in nanoseconds. For example, if the resolution is 1us, this returns 1000.

Note: Some implementations return arbitrary resolution because there's no perfect alternative. For example, according to the source in time.go, windows monotonic resolution can be 15ms. See /RATIONALE.md.

type ExitError

type ExitError struct {
	// contains filtered or unexported fields
}

ExitError is returned to a caller of api.Function when api.Module CloseWithExitCode was invoked, or context.Context passed to api.Function Call was canceled or reached the Timeout.

ExitCode zero value means success while any other value is an error.

Here's an example of how to get the exit code:

main := module.ExportedFunction("main")
if err := main(ctx); err != nil {
	if exitErr, ok := err.(*sys.ExitError); ok {
		// This means your module exited with non-zero code!
	}
--snip--

Note: While possible the reason of this was "proc_exit" from "wasi_snapshot_preview1", it could be from other host functions, for example an AssemblyScript's abort handler, or any arbitrary caller of CloseWithExitCode.

See https://github.com/WebAssembly/WASI/blob/main/phases/snapshot/docs.md#proc_exit and https://www.assemblyscript.org/concepts.html#special-imports

Note: In the case of context cancellation or timeout, the api.Module from which the api.Function created is closed.

func NewExitError

func NewExitError(exitCode uint32) *ExitError

func (*ExitError) Error

func (e *ExitError) Error() string

Error implements the error interface.

func (*ExitError) ExitCode

func (e *ExitError) ExitCode() uint32

ExitCode returns zero on success, and an arbitrary value otherwise.

func (*ExitError) Is

func (e *ExitError) Is(err error) bool

Is allows use via errors.Is

type Nanosleep

type Nanosleep func(ns int64)

Nanosleep puts the current goroutine to sleep for at least ns nanoseconds.

type Nanotime

type Nanotime func() int64

Nanotime returns nanoseconds since an arbitrary start point, used to measure elapsed time. This is sometimes referred to as a tick or monotonic time.

Note: There are no constraints on the value return except that it increments. For example, -1 is a valid if the next value is >= 0.

type Osyield

type Osyield func()

Osyield yields the processor, typically to implement spin-wait loops.

type Walltime

type Walltime func() (sec int64, nsec int32)

Walltime returns the current unix/epoch time, seconds since midnight UTC 1 January 1970, with a nanosecond fraction.