将 JavaScript 字符串传递给编译为 WebAssembly 的 Rust 函数 [英] Passing a JavaScript string to a Rust function compiled to WebAssembly
问题描述
我有这个简单的 Rust 函数:
I have this simple Rust function:
#[no_mangle]
pub fn compute(operator: &str, n1: i32, n2: i32) -> i32 {
match operator {
"SUM" => n1 + n2,
"DIFF" => n1 - n2,
"MULT" => n1 * n2,
"DIV" => n1 / n2,
_ => 0
}
}
我正在成功地将它编译到 WebAssembly,但是没有设法将 operator
参数从 JS 传递给 Rust.
I am compiling this to WebAssembly successfully, but don't manage to pass the operator
parameter from JS to Rust.
调用 Rust 函数的 JS 代码行如下所示:
The JS line which calls the Rust function looks like this:
instance.exports.compute(operator, n1, n2);
operator
是一个 JS String
和 n1
, n2
是 JS Number
s.
operator
is a JS String
and n1
, n2
are JS Number
s.
n1
和 n2
正确传递并且可以在编译函数中读取,所以我猜问题是我如何传递字符串.我想它是作为从 JS 到 WebAssembly 的指针传递的,但找不到关于它是如何工作的证据或材料.
n1
and n2
are passed properly and can be read inside the compiled function so I guess the problem is how I pass the string around. I imagine it is passed as a pointer from JS to WebAssembly but can't find evidence or material about how this works.
我不使用 Emscripten 并希望保持独立(编译目标 wasm32-unknown-unknown
),但我看到他们将编译的函数包装在 Module.cwrap
,也许这会有所帮助?
I am not using Emscripten and would like to keep it standalone (compilation target wasm32-unknown-unknown
), but I see they wrap their compiled functions in Module.cwrap
, maybe that could help?
推荐答案
最简单最地道的解决方案
大多数人应该使用wasm-bindgen,这使得整个过程很多 更简单!
Easiest and most idiomatic solution
Most people should use wasm-bindgen, which makes this whole process much simpler!
要在 JavaScript 和 Rust 之间传输字符串数据,你需要决定
To transfer string data between JavaScript and Rust, you need to decide
- 文本的编码:UTF-8(Rust 原生)或 UTF-16(JS 原生).
- 谁将拥有内存缓冲区:JS(调用者)或 Rust(被调用者).
- 如何表示字符串数据和长度:以 NUL 结尾(C 风格)或不同长度(Rust 风格).
- 如何传达数据和长度(如果它们是分开的).
常见设置
为 WASM 构建 C dylib 以帮助它们缩小尺寸非常重要.
Common setup
It's important to build C dylibs for WASM to help them be smaller in size.
Cargo.toml
[package]
name = "quick-maths"
version = "0.1.0"
authors = ["An Devloper <an.devloper@example.com>"]
[lib]
crate-type = ["cdylib"]
.cargo/config
[target.wasm32-unknown-unknown]
rustflags = [
"-C", "link-args=--import-memory",
]
package.json
{
"name": "quick-maths",
"version": "0.1.0",
"main": "index.js",
"author": "An Devloper <an.devloper@example.com>",
"license": "MIT",
"scripts": {
"example": "node ./index.js"
},
"dependencies": {
"fs-extra": "^8.0.1",
"text-encoding": "^0.7.0"
}
}
我使用的是 NodeJS 12.1.0.
I'm using NodeJS 12.1.0.
执行
$ rustup component add rust-std --target wasm32-unknown-unknown
$ cargo build --release --target wasm32-unknown-unknown
解决方案 1
我决定:
- 将JS字符串转换为UTF-8,这意味着
TextEncoder
JS API 是最合适的. - 调用者应该拥有内存缓冲区.
- 将长度设为单独的值.
- 应该进行另一个结构和分配来保存指针和长度.
lib/src.rs
// A struct with a known memory layout that we can pass string information in
#[repr(C)]
pub struct JsInteropString {
data: *const u8,
len: usize,
}
// Our FFI shim function
#[no_mangle]
pub unsafe extern "C" fn compute(s: *const JsInteropString, n1: i32, n2: i32) -> i32 {
// Check for NULL (see corresponding comment in JS)
let s = match s.as_ref() {
Some(s) => s,
None => return -1,
};
// Convert the pointer and length to a `&[u8]`.
let data = std::slice::from_raw_parts(s.data, s.len);
// Convert the `&[u8]` to a `&str`
match std::str::from_utf8(data) {
Ok(s) => real_code::compute(s, n1, n2),
Err(_) => -2,
}
}
// I advocate that you keep your interesting code in a different
// crate for easy development and testing. Have a separate crate
// with the FFI shims.
mod real_code {
pub fn compute(operator: &str, n1: i32, n2: i32) -> i32 {
match operator {
"SUM" => n1 + n2,
"DIFF" => n1 - n2,
"MULT" => n1 * n2,
"DIV" => n1 / n2,
_ => 0,
}
}
}
index.js
const fs = require('fs-extra');
const { TextEncoder } = require('text-encoding');
// Allocate some memory.
const memory = new WebAssembly.Memory({ initial: 20, maximum: 100 });
// Connect these memory regions to the imported module
const importObject = {
env: { memory }
};
// Create an object that handles converting our strings for us
const memoryManager = (memory) => {
var base = 0;
// NULL is conventionally at address 0, so we "use up" the first 4
// bytes of address space to make our lives a bit simpler.
base += 4;
return {
encodeString: (jsString) => {
// Convert the JS String to UTF-8 data
const encoder = new TextEncoder();
const encodedString = encoder.encode(jsString);
// Organize memory with space for the JsInteropString at the
// beginning, followed by the UTF-8 string bytes.
const asU32 = new Uint32Array(memory.buffer, base, 2);
const asBytes = new Uint8Array(memory.buffer, asU32.byteOffset + asU32.byteLength, encodedString.length);
// Copy the UTF-8 into the WASM memory.
asBytes.set(encodedString);
// Assign the data pointer and length values.
asU32[0] = asBytes.byteOffset;
asU32[1] = asBytes.length;
// Update our memory allocator base address for the next call
const originalBase = base;
base += asBytes.byteOffset + asBytes.byteLength;
return originalBase;
}
};
};
const myMemory = memoryManager(memory);
fs.readFile('./target/wasm32-unknown-unknown/release/quick_maths.wasm')
.then(bytes => WebAssembly.instantiate(bytes, importObject))
.then(({ instance }) => {
const argString = "MULT";
const argN1 = 42;
const argN2 = 100;
const s = myMemory.encodeString(argString);
const result = instance.exports.compute(s, argN1, argN2);
console.log(result);
});
执行
$ yarn run example
4200
解决方案 2
我决定:
- 将JS字符串转换为UTF-8,这意味着
TextEncoder
JS API 是最合适的. - 模块应该拥有内存缓冲区.
- 将长度设为单独的值.
- 使用
Box
作为底层数据结构.这允许 Rust 代码进一步使用分配.
- To convert JS strings to UTF-8, which means that the
TextEncoder
JS API is the best fit. - The module should own the memory buffer.
- To have the length be a separate value.
- To use a
Box<String>
as the underlying data structure. This allows the allocation to be further used by Rust code.
src/lib.rs
// Very important to use `transparent` to prevent ABI issues
#[repr(transparent)]
pub struct JsInteropString(*mut String);
impl JsInteropString {
// Unsafe because we create a string and say it's full of valid
// UTF-8 data, but it isn't!
unsafe fn with_capacity(cap: usize) -> Self {
let mut d = Vec::with_capacity(cap);
d.set_len(cap);
let s = Box::new(String::from_utf8_unchecked(d));
JsInteropString(Box::into_raw(s))
}
unsafe fn as_string(&self) -> &String {
&*self.0
}
unsafe fn as_mut_string(&mut self) -> &mut String {
&mut *self.0
}
unsafe fn into_boxed_string(self) -> Box<String> {
Box::from_raw(self.0)
}
unsafe fn as_mut_ptr(&mut self) -> *mut u8 {
self.as_mut_string().as_mut_vec().as_mut_ptr()
}
}
#[no_mangle]
pub unsafe extern "C" fn stringPrepare(cap: usize) -> JsInteropString {
JsInteropString::with_capacity(cap)
}
#[no_mangle]
pub unsafe extern "C" fn stringData(mut s: JsInteropString) -> *mut u8 {
s.as_mut_ptr()
}
#[no_mangle]
pub unsafe extern "C" fn stringLen(s: JsInteropString) -> usize {
s.as_string().len()
}
#[no_mangle]
pub unsafe extern "C" fn compute(s: JsInteropString, n1: i32, n2: i32) -> i32 {
let s = s.into_boxed_string();
real_code::compute(&s, n1, n2)
}
mod real_code {
pub fn compute(operator: &str, n1: i32, n2: i32) -> i32 {
match operator {
"SUM" => n1 + n2,
"DIFF" => n1 - n2,
"MULT" => n1 * n2,
"DIV" => n1 / n2,
_ => 0,
}
}
}
index.js
const fs = require('fs-extra');
const { TextEncoder } = require('text-encoding');
class QuickMaths {
constructor(instance) {
this.instance = instance;
}
difference(n1, n2) {
const { compute } = this.instance.exports;
const op = this.copyJsStringToRust("DIFF");
return compute(op, n1, n2);
}
copyJsStringToRust(jsString) {
const { memory, stringPrepare, stringData, stringLen } = this.instance.exports;
const encoder = new TextEncoder();
const encodedString = encoder.encode(jsString);
// Ask Rust code to allocate a string inside of the module's memory
const rustString = stringPrepare(encodedString.length);
// Get a JS view of the string data
const rustStringData = stringData(rustString);
const asBytes = new Uint8Array(memory.buffer, rustStringData, encodedString.length);
// Copy the UTF-8 into the WASM memory.
asBytes.set(encodedString);
return rustString;
}
}
async function main() {
const bytes = await fs.readFile('./target/wasm32-unknown-unknown/release/quick_maths.wasm');
const { instance } = await WebAssembly.instantiate(bytes);
const maffs = new QuickMaths(instance);
console.log(maffs.difference(100, 201));
}
main();
执行
$ yarn run example
-101
<小时>
请注意,此过程可用于其他类型.您只需要"决定如何将数据表示为双方同意的一组字节,然后将其发送.
Note that this process can be used for other types. You "just" have to decide how to represent data as a set of bytes that both sides agree on then send it across.
另见:
- 使用 WebAssembly JavaScript API
TextEncoder
APIUint8Array
/Uint32Array
/TypedArray
一个>WebAssembly.Memory代码>
- 你好,Rust!— 导入内存缓冲区
- 如何在 WebAssembly 中从 Rust 返回字符串(或类似字符串)?
这篇关于将 JavaScript 字符串传递给编译为 WebAssembly 的 Rust 函数的文章就介绍到这了,希望我们推荐的答案对大家有所帮助,也希望大家多多支持IT屋!