ssvm-napi

KO | EN

gitlite — search

#javascript #hacktoberfest #typescript #golang #machine-learning #rust #linux #windows #cli #kubernetes #vue #pytorch #ios #open-source

(★ 13)

SSVM Node.js Addon

ssvm-napi Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Second State WebAssembly VM for Node.js Addon

The [Second State VM (SSVM)](https://github.com/second-state/ssvm) is a high-performance WebAssembly runtime optimized for server-side applications. This project provides support for accessing SSVM 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 SSVM addon could interact with the wasm files generated by the [ssvmup](https://github.com/second-state/ssvmup) compiler tool.

## NOTICE

SSVM Node.js Addon is in active development.

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 source during addon installation.

## Requirements

After SSVM Napi 0.4.0 release, we upgrade the base image from `Ubuntu 18.04` to `Ubuntu 20.04`.

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)

## Prepare environment

### Use our docker image (recommended)

```bash
$ docker pull secondstate/ssvm
```

### For ubuntu 20.04

```bash
# Tools and libraries
$ sudo apt install -y \
	software-properties-common \
	cmake \
	libboost-all-dev

# And you will need to install llvm for ssvm-aot tools
$ sudo apt install -y \
	llvm-dev \
	liblld-10-dev

# SSVM supports both clang++ and g++ compilers
# You can choose one of them for building this project
$ sudo apt install -y gcc g++
$ sudo apt install -y clang
```

### Verify the version of llvm

```bash
$ sudo apt list | grep llvm
...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
...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: `ssvm.VM(wasm, ssvm_options) -> vm_instance`
* Create a ssvm instance by given wasm file and options.
* Arguments:
	* `wasm`: Input wasm file, can be the following three 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 SSVM execution environment.
		* `options` <JS Object>
			* `args` <JS Array>: An array of strings that Wasm application will get as function arguments. Default: `[]`.
			* `env` <JS Object>: An object like `process.env` that Wasm application will get as its environment variables. Default: `{}`.
			* `preopens` <JS Object>: An object which maps '<guest_path>:<host_path>'. E.g. `{'/sandbox': '/some/real/path/that/wasm/can/access'}` Default: `{}`.
			* `EnableWasiStartFunction` <Boolean>: This option will disable wasm-bindgen mode and prepare the working environment for standalone wasm program. If you want to run an appliation with `main()`, you should set this to `true`. Default: `false`.
			* `EnableAOT` <Boolean>: This option will enable ssvm aot mode. Default: `false`.
			* `EnableMeasurement` <Boolean>: This option will enable measurement but decrease its performance. Default: `false`.
			* `AllowCommands` <JS Array>: An array of strings that indicate what commands are allowed to execute in the SSVM Process Module. Default `[]`.
			* `AllowAllCommands` <Boolean>: Allow users to call any command in the SSVM Process Module. This option will overwrite the `AllowCommands`. Default: `false`.
* Return value:
	* `vm_instance`: A ssvm 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` <String>: The function name which users want to emit.
	* `args` <Integer/String/Uint8Array>\*: 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` <String>: The function name which users want to emit.
	* `args` <Integer/String/Uint8Array>\*: 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` <String>: The function name which users want to emit.
	* `args` <Integer/String/Uint8Array>\*: 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` <String>: The function name which users want to emit.
	* `args` <Integer/String/Uint8Array>\*: 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` <String>: The function name which users want to emit.
	* `args` <Integer/String/Uint8Array>\*: 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` <String>: The function name which users want to emit.
	* `args` <Integer/String/Uint8Array>\*: 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` <String>: The function name which users want to emit.
	* `args` <Integer/String/Uint8Array>\*: 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 SSVM AOT compiler.
* Return `false` when the compilation failed.
```javascript
// Compile only
let vm = ssvm.VM("/path/to/wasm/file", options);
vm.Compile("/path/to/aot/file");

// When you want to run the compiled file
let vm = ssvm.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` <Object>
	* `Measure` -> <Boolean>: To show if the measurement is enabled or not.
	* `TotalExecutionTime` -> <Integer>: Total execution time (Wasm exeuction time + Host function execution time) in `` unit.
	* `WasmExecutionTime` -> <Integer>: Wasm instructions execution time in `ns` unit.
	* `HostFunctionExecutionTime` -> <Integer>: Host functions (e.g. eei or wasi functions) execution time in `ns` unit.
	* `InstructionCount` -> <Integer>: The number of executed instructions in this execution.
	* `TotalGasCost` -> <Integer>: The cost of this execution.
	* `InstructionPerSecond` -> <Float>: 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
}
*/
```

ssvm-napi

ssvm-napi Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

ssvm-napi

ssvm-napi Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README