Package io.github.eutro.wasm2j.embed

Class WebAssembly

java.lang.Object

io.github.eutro.wasm2j.embed.WebAssembly

public class WebAssembly
extends Object

A direct implementation of the WebAssembly embedding entry-points as defined in the embedding section of the specification.

Clients do not need to use this class, and are free to directly invoke the more convenient and granular methods and constructors of the relevant classes themselves.

Constructor Summary

Constructors

Constructor	Description
WebAssembly()

Method Summary

Modifier and Type	Method	Description
Func	funcAlloc(@Nullable Store store, ExternType.Func type, MethodHandle handle)	Construct a new function extern.
Object[]	funcInvoke(@Nullable Store store, Func func, Object... args)	Invoke a function extern.
ExternType.Func	funcType(@Nullable Store store, Func func)	Get the type of a function extern.
Global	globalAlloc(@Nullable Store store, ExternType.Global type)	Create a new global with the given type.
Object	globalRead(@Nullable Store store, Global global)	Read the value of a global.
ExternType.Global	globalType(@Nullable Store store, Global global)	Get the type of a global.
void	globalWrite(@Nullable Store store, Global global, Object value)	Write the value of a global.
ExternVal	instanceExport(Instance inst, String name)	Get a named export of the module instance.
Memory	memAlloc(@Nullable Store store, ExternType.Mem type)	Create a new memory with the given type.
int	memGrow(@Nullable Store store, Memory memory, int growByPages)	Grow the memory by a number of pages, filling new pages with 0.
byte	memRead(@Nullable Store store, Memory memory, int addr)	Read a single byte from a memory.
int	memSize(@Nullable Store store, Memory memory)	Get the size of the memory, in pages.
ExternType.Mem	memType(@Nullable Store store, Memory memory)	Get the type of a memory.
void	memWrite(@Nullable Store store, Memory memory, int addr, byte value)	Write a single byte to a memory.
Module	moduleDecode(byte[] bytes)	Decode a binary module from a byte array.
List<Export>	moduleExports(Module module)	Get the exports that this module supplies.
Module	moduleFromNode(ModuleNode node)	Create a module from a JWasm module node.
List<Import>	moduleImports(Module module)	Get the imports that the module requires.
Instance	moduleInstantiate(Store store, Module module, ExternVal[] imports)	Instantiate the module in the given store with the provided values for imports.
Module	moduleParse(String source)	Parse a text module from a string.
void	moduleValidate(Module module)	Validate the module, throwing an exception if the module is invalid.
void	setDebugOutputDirectory(File file)	Set the debug output of stores created by this embedding instance.
Store	storeInit()	Returns a new empty store.
Table	tableAlloc(@Nullable Store store, ExternType.Table type)	Construct a new table with the given type.
int	tableGrow(@Nullable Store store, Table table, int growBy, Object fillWith)	Grow the table by a number of elements, filling it with the given value.
Object	tableRead(@Nullable Store store, Table table, int i)	Get an element of the table.
int	tableSize(@Nullable Store store, Table table)	Get the size of a table.
ExternType.Table	tableType(@Nullable Store store, Table table)	Get the type of a table extern.
void	tableWrite(@Nullable Store store, Table table, int i, Object value)	Set an element of the table.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

WebAssembly

public WebAssembly()

Method Details

setDebugOutputDirectory

public void setDebugOutputDirectory(File file)

Set the debug output of stores created by this embedding instance.

Parameters:

file - The debug directory.

See Also:

• Store.setDebugOutput(File)

storeInit

public Store storeInit()

Returns a new empty store.

Returns:

The new store.

See Also:

• Store.init()

moduleDecode

public Module moduleDecode(byte[] bytes)

Decode a binary module from a byte array.

Parameters:

bytes - The byte array.

Returns:

The decoded module

See Also:

• Module.decode(byte[])

moduleParse

public Module moduleParse(String source)

Parse a text module from a string.

Parameters:

source - The source string.

Returns:

The parsed module.

See Also:

• Module.parse(String)

moduleFromNode

public Module moduleFromNode(ModuleNode node)

Create a module from a JWasm module node.

The module node will be copied, to prevent exterior mutation.

Parameters:

node - The module node.

Returns:

The new module.

See Also:

• Module.fromNode(ModuleNode)

moduleValidate

public void moduleValidate(Module module)

Validate the module, throwing an exception if the module is invalid.

This is idempotent, and will not run validation again if the module has already been validated.

Parameters:

module - The module to validate.

See Also:

• Module.validate()

moduleInstantiate

public Instance moduleInstantiate(Store store,
 Module module,
 ExternVal[] imports)

Instantiate the module in the given store with the provided values for imports.

The imports must be in the same order as those returned for Module.imports().

Parameters:

store - The store.

module - The module to instantiate.

imports - The supplied imports.

Returns:

The instantiated module.

See Also:

• Module.instantiate(Store, ExternVal[])

moduleImports

public List<Import> moduleImports(Module module)

Get the imports that the module requires.

Parameters:

module - The module.

Returns:

The list of imports.

See Also:

• Module.imports()

moduleExports

public List<Export> moduleExports(Module module)

Get the exports that this module supplies.

Parameters:

module - The module.

Returns:

The list of exports.

See Also:

• Module.exports()

instanceExport

public ExternVal instanceExport(Instance inst,
 String name)

Get a named export of the module instance.

Parameters:

inst - The module instance.

name - The name of the export.

Returns:

The export.

See Also:

• Instance.getExport(String)

funcAlloc

public Func funcAlloc(@Nullable
 @Nullable Store store,
 ExternType.Func type,
 MethodHandle handle)

Construct a new function extern.

Parameters:

store - The store. Ignored.

type - The function type.

handle - The method handle.

Returns:

The allocated function.

See Also:

• HandleFunc(ExternType.Func, MethodHandle)

funcType

public ExternType.Func funcType(@Nullable
 @Nullable Store store,
 Func func)

Get the type of a function extern.

Parameters:

store - The store. Ignored.

func - The function.

Returns:

The type of the function.

See Also:

• Func.getType()

funcInvoke

public Object[] funcInvoke(@Nullable
 @Nullable Store store,
 Func func,
 Object... args)

Invoke a function extern.

Parameters:

store - The store. Ignored.

func - The function.

args - The function arguments.

Returns:

The type of the function.

See Also:

• Func.invoke(Object...)

tableAlloc

public Table tableAlloc(@Nullable
 @Nullable Store store,
 ExternType.Table type)

Construct a new table with the given type.

Parameters:

store - The store. Ignored.

type - The table type.

Returns:

A new table.

See Also:

• ArrayTable(ExternType.Table)

tableType

public ExternType.Table tableType(@Nullable
 @Nullable Store store,
 Table table)

Get the type of a table extern.

Parameters:

store - The store. Ignored.

table - The table.

Returns:

The table's type.

See Also:

• Table.getType()

tableRead

public Object tableRead(@Nullable
 @Nullable Store store,
 Table table,
 int i)

Get an element of the table.

Parameters:

store - The store. Ignored.

table - The table.

i - The element index.

Returns:

The element.

See Also:

• Table.get(int)

tableWrite

public void tableWrite(@Nullable
 @Nullable Store store,
 Table table,
 int i,
 Object value)

Set an element of the table.

Parameters:

store - The store. Ignored.

table - The table.

i - The element index.

value - The element.

See Also:

• Table.set(int, Object)

tableSize

public int tableSize(@Nullable
 @Nullable Store store,
 Table table)

Get the size of a table.

Parameters:

store - The store. Ignored.

table - The table.

Returns:

The size of the table.

See Also:

• Table.size()

tableGrow

public int tableGrow(@Nullable
 @Nullable Store store,
 Table table,
 int growBy,
 Object fillWith)

Grow the table by a number of elements, filling it with the given value.

This operation is allowed to fail (and must fail if the upper limit is exceeded), in which case -1 should be returned.

Parameters:

store - The store. Ignored.

table - The table.

growBy - The number of elements to grow by.

fillWith - The value to fill new elements with.

Returns:

The old size of the table.

See Also:

• Table.grow(int, Object)

memAlloc

public Memory memAlloc(@Nullable
 @Nullable Store store,
 ExternType.Mem type)

Create a new memory with the given type.

Parameters:

store - The store. Ignored.

type - The type.

Returns:

The new memory.

See Also:

• Memory.alloc(ExternType.Mem)

memType

public ExternType.Mem memType(@Nullable
 @Nullable Store store,
 Memory memory)

Get the type of a memory.

Parameters:

store - The store. Ignored.

memory - The memory.

Returns:

The memory type.

See Also:

• Memory.getType()

memRead

public byte memRead(@Nullable
 @Nullable Store store,
 Memory memory,
 int addr)

Read a single byte from a memory.

Using this is discouraged, see Memory.read(int).

Parameters:

store - The store. Ignored.

memory - The memory.

addr - The memory address.

Returns:

The byte.

See Also:

• Memory.read(int)

memWrite

public void memWrite(@Nullable
 @Nullable Store store,
 Memory memory,
 int addr,
 byte value)

Write a single byte to a memory.

Using this is discouraged, see Memory.write(int, byte).

Parameters:

store - The store. Ignored.

memory - The memory.

addr - The memory address.

value - The byte.

See Also:

• Memory.write(int, byte)

memSize

public int memSize(@Nullable
 @Nullable Store store,
 Memory memory)

Get the size of the memory, in pages.

Parameters:

store - The store. Ignored.

memory - The memory.

Returns:

The size of the memory, in pages.

See Also:

• Memory.size()
• Opcodes.PAGE_SIZE

memGrow

public int memGrow(@Nullable
 @Nullable Store store,
 Memory memory,
 int growByPages)

Grow the memory by a number of pages, filling new pages with 0.

This operation is allowed to fail (and must fail if the upper limit is exceeded), in which case -1 should be returned.

Parameters:

store - The store. Ignored.

memory - The memory.

growByPages - The number of pages to grow by, interpreted as an unsigned integer.

Returns:

The old size, or -1 if the memory was not grown.

See Also:

• Memory.size()
• Opcodes.PAGE_SIZE

globalAlloc

public Global globalAlloc(@Nullable
 @Nullable Store store,
 ExternType.Global type)

Create a new global with the given type.

Parameters:

store - The store. Ignored.

type - The type.

Returns:

The global.

See Also:

• BoxGlobal(ExternType.Global)

globalType

public ExternType.Global globalType(@Nullable
 @Nullable Store store,
 Global global)

Get the type of a global.

Parameters:

store - The store. Ignored.

global - The global.

Returns:

The global type.

See Also:

• Global.getType()

globalRead

public Object globalRead(@Nullable
 @Nullable Store store,
 Global global)

Read the value of a global.

Parameters:

store - The store. Ignored.

global - The global.

Returns:

The value of the global.

See Also:

• Global.get()

globalWrite

public void globalWrite(@Nullable
 @Nullable Store store,
 Global global,
 Object value)

Write the value of a global.

Should fail if the global is immutable.

Parameters:

store - The store. Ignored.

global - The global.

value - The new value of the global.

See Also:

• Global.set(Object)