Annotations
The annotation processor generates host functions from annotated Java methods, and typed Java bindings from a Wasm module, so you do not write the HostFunction boilerplate by hand.
Setup
Add the annotations dependency:
<dependency>
<groupId>run.endive</groupId>
<artifactId>annotations</artifactId>
<version>${endive.version}</version>
</dependency>
and register annotations-processor as an annotation processor of the Java compiler, with Maven:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<annotationProcessorPaths>
<path>
<groupId>run.endive</groupId>
<artifactId>annotations-processor</artifactId>
<version>${endive.version}</version>
</path>
</annotationProcessorPaths>
</configuration>
</plugin>
Host modules
Annotate the methods of a class and the processor generates one host function per method:
@HostModule("demo")
public final class Demo {
private final Random random = new Random();
@WasmExport
public long add(int a, int b) {
return a + b;
}
@WasmExport // the Wasm name is random_get
public void randomGet(Memory memory, int ptr, int len) {
byte[] data = new byte[len];
random.nextBytes(data);
memory.write(ptr, data);
}
public HostFunction[] toHostFunctions() {
return Demo_ModuleFactory.toHostFunctions(this);
}
}
The @HostModule annotation marks the class as a host module and specifies the module name for
all the host functions. The @WasmExport annotation marks a method as host function and optionally
specifies the name of the function. If the name is not specified, then the Java method name is
converted from camel case to snake case, as is a common convention in Wasm.
The Demo_ModuleFactory class in toHostFunctions() is generated by the annotation processor.
Host functions must be instance methods of the class. Static methods are not supported. This is because host functions will typically interact with instance state in the host class.
To use the host module, you need to instantiate the host module and fetch the host functions:
import run.endive.runtime.ImportValues;
var demo = new Demo();
var imports = ImportValues.builder().addFunction(demo.toHostFunctions()).build();
Type conversions
Parameters and return values are converted as follows:
| Java type | Wasm type |
|---|---|
int | i32 |
long | i64 |
float | f32 |
double | f64 |
Parameters can also be a String annotated with @Buffer (passed as an i32 pointer and an i32 length) or @CString (an i32 pointer to a NUL-terminated string), both read from the module's memory, and Instance or Memory, which receive the calling instance or its memory without a Wasm parameter.
WasmModuleInterface
If you are using the build-time compiler, you can use the moduleInterface parameter in the Maven plugin instead of the annotation processor. This is simpler and avoids the setup described below. See Generating Module Exports and Imports.
If you already have a Wasm module and want to generate scaffolded Java code to interact with it, you can use the @WasmModuleInterface annotation.
@WasmModuleInterface("demo.wasm")
public final class Demo {}
The annotation accepts a single argument, which can be either:
- The location of the Wasm module on the current classpath (transitive references are not supported).
- An absolute URI pointing to the Wasm module, in the form of
file://....
This annotation generates several things, depending on the provided module:
ModuleExports: Represents the Wasm module's exported functions, mapped to typed Java parameters and return values.ModuleImports: Represents the module's imported host functions and includes a convenienttoImportValues()method to obtain ImportValues after implementing the interfaces.
You can find examples of how to use the generated code in the annotations/it folder of the repository.