Od Rusta do WASM za pomocą wasm-pack i React

Standardowy przepływ pracy Rust-to-WASM wykorzystuje dwa narzędzia: wasm-pack koordynuje proces budowania (kompiluje Rust do WASM, uruchamia wasm-bindgen i generuje pakiet npm), a wasm-bindgen generuje powiązania JavaScript, dzięki którym funkcje Rust można wywoływać jak zwykłe funkcje JavaScript z prawidłową obsługą typów.

Atrybut #[wasm_bindgen] oznacza funkcje, struktury i metody Rust przeznaczone do eksportu do JavaScriptu. Bez niego funkcja zostaje skompilowana do WASM, ale nie jest dostępna z poziomu JavaScriptu. Po oznaczeniu funkcji atrybutem #[wasm_bindgen] wasm-bindgen generuje kod glue JavaScript, który obsługuje konwersję argumentów i wartości zwracanych.

Minimalna wyeksportowana funkcja Rust: use wasm_bindgen::prelude::*; #[wasm_bindgen] pub fn add(a: u32, b: u32) -> u32 { a + b }. Funkcja przyjmuje dwie 32-bitowe liczby bez znaku i zwraca jedną liczbę tego typu. wasm-bindgen generuje kod JavaScript, który wywołuje tę funkcję z argumentami liczbowymi i zwraca wynik liczbowy.

W katalogu crate'a Rust należy uruchomić polecenie wasm-pack build --target web. Kompiluje ono kod Rust do WASM, uruchamia wasm-bindgen w celu wygenerowania powiązań JavaScript i tworzy katalog pkg/ zawierający binarny plik .wasm, moduł JavaScript glue oraz definicje typów TypeScript.

Wygenerowany moduł należy zaimportować w komponencie React: import init, { add } from '../pkg/my_lib'. Funkcja init ładuje i inicjalizuje binarny moduł WASM — należy wywołać ją raz w useEffect. Po zakończeniu inicjalizacji można bezpośrednio wywoływać wyeksportowane funkcje: const result = add(2, 3).

W przypadku złożonych danych wykraczających poza liczby prymitywne wasm-bindgen udostępnia js_sys::Array (tablica JavaScript), js_sys::Object (obiekt JavaScript) oraz wasm_bindgen::JsValue (dowolna wartość JavaScript). Typy te pozwalają funkcjom Rust przyjmować i zwracać tablice oraz obiekty JavaScript, choć wiąże się to z większym narzutem serializacji niż w przypadku typów prymitywnych.

Kluczowa zasada wydajności jest następująca: należy przechowywać dane w pamięci WASM i wykonywać tam wszystkie obliczenia. Dane należy przekazać raz, wykonać obliczenia, a następnie zwrócić wyłącznie końcowy wynik. Należy unikać wzorców, które przy każdym kroku wielokrotnie przenoszą dane przez granicę WASM. Narzut pojedynczego przekroczenia granicy jest niewielki, ale kumuluje się w intensywnie wykonywanych pętlach.

Crate serde-wasm-bindgen umożliwia serializowanie struktur Rust do obiektów JavaScript i z powrotem przy użyciu Serde. Należy opatrzyć strukturę adnotacją #[derive(Serialize, Deserialize)] oraz użyć funkcji serde_wasm_bindgen::to_value() i from_value(). Jest to standardowe podejście do przekazywania złożonych danych strukturalnych.

Długotrwałe obliczenia WASM blokują wątek, w którym są wykonywane. Należy umieścić WASM w Web Workerze, aby zwolnić główny wątek Reacta. Należy utworzyć plik workera, który zainicjalizuje moduł WASM i będzie obsługiwać komunikaty. Dane należy wysyłać do workera za pomocą postMessage, odbierać wyniki za pośrednictwem zdarzenia message, a następnie aktualizować stan Reacta otrzymanym wynikiem.

wasm-pack automatycznie generuje pliki deklaracji TypeScript (.d.ts) dla wszystkich eksportowanych funkcji i typów. Zapewnia to pełne bezpieczeństwo typów w projekcie React TypeScript podczas wywoływania funkcji Rust. Wygenerowane typy odzwierciedlają sygnatury funkcji Rust — add(a: number, b: number): number — dzięki czemu autouzupełnianie w IDE działa prawidłowo.

Binarne pliki WASM mają zwykle rozmiar od 100kb do 2MB po optymalizacji. Należy włączyć wasm-opt podczas kompilacji za pomocą wasm-pack, ustawiając opt-level = "z" w profilu wydania pliku Cargo.toml, aby zastosować agresywną optymalizację rozmiaru. Pliki WASM należy serwować z nagłówkiem Content-Type: application/wasm oraz włączyć HTTP/2, aby przeglądarka mogła wydajnie strumieniować plik binarny.

Jaki jest cel atrybutu #[wasm_bindgen] w kodzie Rust?

wasm-pack build --target web kompiluje Rust do WASM i generuje powiązania JavaScript za pośrednictwem wasm-bindgen. Należy oznaczyć eksportowane funkcje adnotacją #[wasm_bindgen]. W React należy zaimportować init oraz eksportowane funkcje, wywołać init() w useEffect, a następnie wywoływać funkcje tak jak zwykłe funkcje JavaScript. Do serializowania złożonych struktur należy używać serde-wasm-bindgen. Długotrwałe obliczenia WASM należy uruchamiać w Web Workerach, aby zwolnić główny wątek Reacta.