https://github.com/second-state/wasmedge-extensions
WasmEdge for Node.js Addon with extensions
https://github.com/second-state/wasmedge-extensions
Last synced: 8 months ago
JSON representation
WasmEdge for Node.js Addon with extensions
- Host: GitHub
- URL: https://github.com/second-state/wasmedge-extensions
- Owner: second-state
- License: apache-2.0
- Archived: true
- Created: 2021-09-12T08:27:16.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2021-12-14T09:49:11.000Z (over 4 years ago)
- Last Synced: 2025-01-20T02:12:08.899Z (over 1 year ago)
- Language: C++
- Homepage:
- Size: 183 KB
- Stars: 3
- Watchers: 6
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# WasmEdge for Node.js Addon with extensions
The [WasmEdge (previously known as Second State VM, SSVM)](https://github.com/WasmEdge/WasmEdge) is a high-performance WebAssembly runtime optimized for server-side applications. This project provides support for accessing WasmEdge as a Node.js addon. It allows Node.js applications to call WebAssembly functions written in Rust or other high-performance languages. [Why do you want to run WebAssembly on the server-side?](https://cloud.secondstate.io/server-side-webassembly/why) The WasmEdge addon could interact with the wasm files generated by the [rustwasmc](https://github.com/second-state/rustwasmc) compiler tool.
## NOTICE
In the current stage, our prebuilt version **only supports** x86\_64 and aarch64 Linux.
Or you could use `--build-from-source` flag to build from the source during addon installation.
## WasmEdge versions
There are mappings of wasmedge-extensions versoins and corresponding [WasmEdge](https://github.com/WasmEdge/WasmEdge) versions:
| wasmedge-extensions | WasmEdge |
| -------------------- | ----------- |
| 0.8.1 | 0.8.1 |
| 0.8.2 | 0.8.2 |
| 0.8.3 | 0.8.2 |
| 0.9.0-rc.1 | 0.9.0-rc.1 |
| 0.9.0 | 0.9.0 |
## Development Requirements
Users should install the dependencies by the following requirments:
* boost >= 1.65.0
* llvm >= 10
* liblld-10-dev >= 10
* libstdc++6 >= 6.0.28 (GLIBCXX >= 3.4.28)
* g++ version >= 9.0 (Optional, if you have to build from source)
### TensorFlow extensions
Please refer to [WasmEdge install section](https://github.com/WasmEdge/WasmEdge/blob/master/docs/install.md) to install the WasmEdge with other extensions.
## Prepare the environment
### Use our docker image or dockerfile
```bash
$ docker pull secondstate/ssvm-extensions
# Or you can build it on your local environment.
$ docker build . -f utils/docker/Dockerfile -t secondstate/ssvm-extensions
```
### Verify the version of llvm
```bash
sudo apt list | grep llvm
# Expected output
...omitted...
llvm-dev/focal,now 1:10.0-50~exp1 amd64 [installed]
llvm-runtime/focal,now 1:10.0-50~exp1 amd64 [installed,automatic]
llvm/focal,now 1:10.0-50~exp1 amd64 [installed,automatic]
...omitted...
# If the version is 1:10.x, then your llvm version is correct.
```
### Verify the version of libstdc++6
```bash
strings /usr/lib/x86_64-linux-gnu/libstdc++.so.6 | grep GLIBCXX
# Expected output
...omitted...
GLIBCXX_3.4.24
GLIBCXX_3.4.25
GLIBCXX_3.4.26
GLIBCXX_3.4.27
GLIBCXX_3.4.28
GLIBCXX_DEBUG_MESSAGE_LENGTH
# If you can find GLIBCXX_3.4.28 in the output, then your libstdc++6 version is correct.
```
### Works with Rust library using Wasm-Bindgen
Please refer to [Tutorial: A Wasm-Bindgen application](./Tutorial_Wasm_Bindgen.md).
### Works with Rust application using standalone wasm32-wasi backend
Please refer to [Tutorial: A standalone wasm32-wasi application](./Tutorial_Wasm32_Wasi.md).
## APIs
### Constructor: `wasmedge.VM(wasm, wasmedge_options) -> vm_instance`
* Create a WasmEdge instance by given wasm file and options.
* Arguments:
* `wasm`: Input wasm file, can be the following two formats:
1. Wasm file path (String, e.g. `/tmp/hello.wasm`)
2. Wasm bytecode format which is the content of a wasm binary file (Uint8Array)
* `options`: An options object for setup the WasmEdge execution environment.
* `options`
* `args` : An array of strings that the Wasm application will get as function arguments. Default: `[]`.
* `env` : An object like `process.env` that Wasm application will get as its environment variables. Default: `{}`.
* `preopens` : An object which maps ':'. E.g. `{'/sandbox': '/some/real/path/that/wasm/can/access'}` Default: `{}`.
* `EnableWasiStartFunction` : This option will disable wasm-bindgen mode and prepare the working environment for the standalone wasm program. If you want to run an application with `main()`, you should set this to `true`. Default: `false`.
* `EnableAOT` : This option will enable WasmEdge AoT mode. Default: `false`.
* `EnableMeasurement` : This option will enable measurement but decrease its performance. Default: `false`.
* `AllowCommands` : An array of strings that indicate what commands are allowed to execute in the WasmEdge Process Module. Default `[]`.
* `AllowAllCommands` : Allow users to call any command in the WasmEdge Process Module. This option will overwrite the `AllowCommands`. Default: `false`.
* Return value:
* `vm_instance`: A WasmEdge instance.
### Methods
#### `Start() -> Integer`
* Emit `_start()` and expect the return value type is `Integer` which represents the error code from `main()`.
* Arguments:
* If you want to append arguments for the standalone wasm program, please set the `args` in `wasi options`.
* Example:
```javascript
let error_code = Start();
```
#### `Run(function_name, args...) -> void`
* Emit `function_name` with `args` and expect the return value type is `void`.
* Arguments:
* `function_name` : The function name which users want to emit.
* `args` \*: The function arguments. The delimiter is `,`
* Example:
```javascript
Run("Print", 1234);
```
#### `RunInt(function_name, args...) -> Integer`
* Emit `function_name` with `args` and expect the return value type is `Integer` (Int32).
* Arguments:
* `function_name` : The function name which users want to emit.
* `args` \*: The function arguments. The delimiter is `,`
* Example:
```javascript
let result = RunInt("Add", 1, 2);
// result should be 3
```
#### `RunUInt(function_name, args...) -> Integer`
* Emit `function_name` with `args` and expect the return value type is `Integer` (UInt32).
* Arguments:
* `function_name` : The function name which users want to emit.
* `args` \*: The function arguments. The delimiter is `,`
* Example:
```javascript
let result = RunInt("Add", 1, 2);
// result should be 3
```
#### `RunInt64(function_name, args...) -> BigInt`
* Emit `function_name` with `args` and expect the return value type is `BigInt` (Int64).
* Arguments:
* `function_name` : The function name which users want to emit.
* `args` \*: The function arguments. The delimiter is `,`
* Example:
```javascript
let result = RunInt("Add", 1, 2);
// result should be 3
```
#### `RunUInt64(function_name, args...) -> BigInt`
* Emit `function_name` with `args` and expect the return value type is `BigInt` (UInt64).
* Arguments:
* `function_name` : The function name which users want to emit.
* `args` \*: The function arguments. The delimiter is `,`
* Example:
```javascript
let result = RunInt("Add", 1, 2);
// result should be 3
```
#### `RunString(function_name, args...) -> String`
* Emit `function_name` with `args` and expect the return value type is `String`.
* Arguments:
* `function_name` : The function name which users want to emit.
* `args` \*: The function arguments. The delimiter is `,`
* Example:
```javascript
let result = RunString("PrintMathScore", "Amy", 98);
// result: "Amy’s math score is 98".
```
#### `RunUint8Array(function_name, args...) -> Uint8Array`
* Emit `function_name` with `args` and expect the return value type is `Uint8Array`.
* Arguments:
* `function_name` : The function name which users want to emit.
* `args` \*: The function arguments. The delimiter is `,`
* Example:
```javascript
let result = RunUint8Array("Hash", "Hello, world!");
// result: "[12, 22, 33, 42, 51]".
```
#### `Compile(output_filename) -> boolean`
* Compile a given wasm file (can be a file path or a byte array) into a native binary whose name is the given `output_filename`.
* This function uses WasmEdge AoT compiler.
* Return `false` when the compilation failed.
```javascript
// Compile only
let vm = wasmedge.VM("/path/to/wasm/file", options);
vm.Compile("/path/to/aot/file");
// When you want to run the compiled file
let vm = wasmedge.VM("/path/to/aot/file", options);
vm.RunXXX("Func", args);
```
#### `GetStatistics() -> Object`
* If you want to enable measurement, set the option `EnableMeasurement` to `true`. But please notice that enabling measurement will significantly affect performance.
* Get the statistics of execution runtime.
* Return Value `Statistics`
* `Measure` -> : To show if the measurement is enabled or not.
* `TotalExecutionTime` -> : Total execution time (Wasm exeuction time + Host function execution time) in `ns` unit.
* `WasmExecutionTime` -> : Wasm instructions execution time in `ns` unit.
* `HostFunctionExecutionTime` -> : Host functions (e.g. eei or wasi functions) execution time in `ns` unit.
* `InstructionCount` -> : The number of executed instructions in this execution.
* `TotalGasCost` -> : The cost of this execution.
* `InstructionPerSecond` -> : The instructions per second of this execution.
```javascript
let result = RunInt("Add", 1, 2);
// result should be 3
let stat = GetStatistics();
/*
If the `EnableMeasurement: true`:
stat = Statistics: {
Measure: true,
TotalExecutionTime: 1512,
WasmExecutionTime: 1481,
HostFunctionExecutionTime: 31,
InstructionCount: 27972,
TotalGasCost: 27972,
InstructionPerSecond: 18887238.35246455
}
Else:
stat = Statistics: {
Measure: false
}
*/
```