Documentation
¶
Overview ¶
Package sys includes constants and types used by both public and internal APIs.
Example (EpochNanos) ¶
This shows typical conversions to sys.EpochNanos type, for sys.Stat_t fields.
package main
import (
"io/fs"
"github.com/AR1011/wazero/sys"
)
var (
walltime sys.Walltime
info fs.FileInfo
st sys.Stat_t
)
func main() {
// Convert an adapted fs.File's fs.FileInfo to Mtim.
st.Mtim = info.ModTime().UnixNano()
// Generate a fake Atim using sys.Walltime passed to wazero.ModuleConfig.
sec, nsec := walltime()
st.Atim = sec*1e9 + int64(nsec)
}
Output:
Example (Inode) ¶
This shows how to return data not defined in fs.FileInfo, notably sys.Inode.
package main
import (
"io/fs"
"math"
"github.com/AR1011/wazero/sys"
)
var info fs.FileInfo
type fileInfoWithSys struct {
fs.FileInfo
st sys.Stat_t
}
func (f *fileInfoWithSys) Sys() any { return &f.st }
func main() {
st := sys.NewStat_t(info)
st.Ino = math.MaxUint64 // arbitrary non-zero value
info = &fileInfoWithSys{info, st}
}
Output:
Index ¶
Examples ¶
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.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
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 EpochNanos ¶
type EpochNanos = int64
EpochNanos is a timestamp in epoch nanoseconds, or zero if unknown.
This defines epoch time the same way as Walltime, except this value is packed into an int64. Common conversions are detailed in the examples.
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 ¶
type Inode ¶
type Inode = uint64
Inode is the file serial number, or zero if unknown.
Any constant value will invalidate functions that use this for equivalence, such as os.SameFile (Stat_t.Ino).
When zero is returned by a `readdir`, some compilers will attempt to get a non-zero value with `lstat`. Those using this for darwin's definition of `getdirentries` conflate zero `d_fileno` with a deleted file, so skip the entry. See /RATIONALE.md for more on this.
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 Stat_t ¶
type Stat_t struct {
// Dev is the device ID of device containing the file.
Dev uint64
// Ino is the file serial number, or zero if not available. See Inode for
// more details including impact returning a zero value.
Ino Inode
// Mode is the same as Mode on fs.FileInfo containing bits to identify the
// type of the file (fs.ModeType) and its permissions (fs.ModePerm).
Mode fs.FileMode
// Nlink is the number of hard links to the file.
//
// Note: This value is platform-specific and often at least one. Linux will
// return 1+N for a directory, where BSD (like Darwin) return 2+N, which
// includes the dot entry.
Nlink uint64
// Size is the length in bytes for regular files. For symbolic links, this
// is length in bytes of the pathname contained in the symbolic link.
Size int64
// Atim is the last data access timestamp in epoch nanoseconds.
Atim EpochNanos
// Mtim is the last data modification timestamp in epoch nanoseconds.
Mtim EpochNanos
// Ctim is the last file status change timestamp in epoch nanoseconds.
Ctim EpochNanos
}
Stat_t is similar to syscall.Stat_t, except available on all operating systems, including Windows.
Notes ¶
- This is used for WebAssembly ABI emulating the POSIX `stat` system call. Fields included are required for WebAssembly ABI including wasip1 (a.k.a. wasix) and wasi-filesystem (a.k.a. wasip2). See https://pubs.opengroup.org/onlinepubs/9699919799/functions/stat.html
- Fields here are required for WebAssembly ABI including wasip1 (a.k.a. wasix) and wasi-filesystem (a.k.a. wasip2).
- This isn't the same as syscall.Stat_t because wazero supports Windows, which doesn't have that type. runtime.GOOS that has this already also have inconsistent field lengths, which complicates wasm binding.
- Use NewStat_t to create this from an existing fs.FileInfo.
- For portability, numeric fields are 64-bit when at least one platform defines it that large.
func NewStat_t ¶
NewStat_t fills a new Stat_t from `info`, including any runtime.GOOS-specific details from fs.FileInfo `Sys`. When `Sys` is already a *Stat_t, it is returned as-is.
Notes ¶
- When already in fs.FileInfo `Sys`, Stat_t must be a pointer.
- When runtime.GOOS is "windows" Stat_t.Ino will be zero.
- When fs.FileInfo `Sys` is nil or unknown, some fields not in fs.FileInfo are defaulted: Stat_t.Atim and Stat_t.Ctim are set to `ModTime`, and are set to ModTime and Stat_t.Nlink is set to 1.
Source Files