Начало работы
Загрузка Wasm в JS
WebAssembly (Wasm) — бинарный формат, выполняющийся в браузерах почти с нативной скоростью. instantiateStreaming загружает и компилирует .wasm-файл. Экспорты — функции, вызываемые из JavaScript.
// Load and instantiate a .wasm module
WebAssembly.instantiateStreaming(fetch('module.wasm'))
.then(result => {
const { instance } = result;
// call exported functions
console.log(instance.exports.add(2, 3)); // 5
});
// Alternative: from ArrayBuffer
const bytes = new Uint8Array([0x00, 0x61, 0x73, 0x6d, 0x01, 0x00, 0x00, 0x00]);
WebAssembly.instantiate(bytes).then(result => {
console.log(result.instance.exports);
});Модули и э кземпляры WebAssembly
WebAssembly.Module — скомпилированное представление без состояния, безопасное для переиспользования в нескольких экземплярах. WebAssembly.Instance хранит состояние выполнения (память, глобальные переменные). Скомпилировать один раз и создать много экземпляров эффективно для параллельных воркеров.
// Two-step: compile then instantiate
const module = await WebAssembly.compile(bytes);
const instance = await WebAssembly.instantiate(module, importObject);
console.log(instance.exports.add(1, 2));
// Module is stateless & shareable across instances
const instance2 = await WebAssembly.instantiate(module, importObject);
// Each instance has its own memory and globalsПоддержка браузеров и определение возможностей
WebAssembly 1.0 поддерживается во всех современных браузерах. Новые предложения (SIMD, исключения, потоки, GC) требуют определения возможностей. WebAssembly.validate проверяет, что байты образуют валидный модуль, без компиляции.
// Check basic WebAssembly support
if (typeof WebAssembly !== 'undefined') {
console.log('WebAssembly is supported');
}
// Verify the engine can actually compile
WebAssembly.validate(new Uint8Array([
0x00, 0x61, 0x73, 0x6d, 0x01, 0x00, 0x00, 0x00
])); // true if valid module
// Feature-detect newer proposals
const hasSIMD = typeof WebAssembly.Module !== 'undefined';
const hasExceptions = 'exceptions' in WebAssembly;Потоковая и обычная загрузка
instantiateStreaming компилирует модуль по мере передачи по сети — быстрее старт. Сервер ОБЯЗАН отдавать 'Content-Type: application/wasm'. Если CDN или статический хостинг не даёт этот заголовок, используйте путь через ArrayBuffer.
// Streaming (preferred): compiles while downloading
WebAssembly.instantiateStreaming(fetch('m.wasm'), imports);
// Non-streaming: must download fully first
const res = await fetch('m.wasm');
const buf = await res.arrayBuffer();
WebAssembly.instantiate(buf, imports);
// Streaming requires correct MIME type:
// Content-Type: application/wasmМагическое число и заголовок Wasm
Магическое число бинарника Wasm — ASCII-строка '\0asm', за которой идёт 4-байтовая версия в little-endian. Этот заголовок позволяет проверить, что файл является Wasm, до компиляции. Формат организован в секции (Type, Import, Function, Memory и т. д.).
// Every .wasm file starts with this 8-byte header:
// 0x00 0x61 0x73 0x6d -> "\0asm"
// 0x01 0x00 0x00 0x00 -> version 1
const magic = [0x00, 0x61, 0x73, 0x6d];
const version = [0x01, 0x00, 0x00, 0x00];
// Quick validity check
function isWasm(bytes) {
return bytes[0] === 0x00 && bytes[1] === 0x61
&& bytes[2] === 0x73 && bytes[3] === 0x6d;
}Hello Wasm (минимальный пример)
Минимальное приложение Wasm: модуль импортирует функцию 'log' из JS и экспортирует 'greet', которая её вызывает. Формат WAT (WebAssembly Text) — читаемое человеком представление, компилируемое в бинарник через wat2wasm. Браузеры выполняют только бинарную форму.
<!-- index.html -->
<script>
WebAssembly.instantiateStreaming(fetch('hello.wasm'))
.then(({ instance }) => {
instance.exports.greet(); // logs "Hello, Wasm!"
});
</script>
;; hello.wat (compiled to hello.wasm via wat2wasm)
(module
(import "console" "log" (func $log (param i32)))
(func (export "greet")
i32.const 72 ;; 'H'
call $log
)
)Текстовый формат WAT
Модуль и S-выражения
WAT (WebAssembly Text format) — текстовое представление Wasm. Всё обёрнут о в s-выражение (module ...). Инструкции пишутся в стековом порядке: сначала операнды, затем операция их потребляет.
;; WAT uses s-expressions: (keyword args...)
(module
;; function definitions, exports, etc. go here
)
;; Nested expressions form the instruction sequence
(module
(func $add (param $a i32) (param $b i32) (result i32)
local.get $a
local.get $b
i32.add
)
(export "add" (func $add))
)Комментарии в WAT
WAT поддерживает два стиля комментариев: ';;' для однострочных и '(; ... ;)' для блочных. Блочные комментарии могут вкладываться и занимать несколько строк — удобно, чтобы отключать куски кода при разработке.
;; Single-line comment (starts with ;;)
(func (export "f")
i32.const 1 ;; push 1
drop ;; discard
)
(; Block comment
can span
multiple lines ;)
(func (export "g")
nop
)Синтаксис определения функций
Функции объявляются через (func ...). Параметры задаются (param $name type), результаты — (result type). '$name' необязателен: без него функции и локальные переменные ссылаются по числовому индексу. Возврат нескольких значений требует предложения multi-value (широко поддерживается).
;; Named function with params and result
(func $name (param $p1 i32) (param $p2 f64) (result i32)
;; body
)
;; Anonymous function (referenced by index)
(func (param i32) (result i32)
local.get 0
)
;; Multiple results (multi-value proposal)
(func $swap (param i32 i32) (result i32 i32)
local.get 1
local.get 0
)Inline export и import
WAT поддерживает inline-аннотации (export "name") и (import "module" "field") на функциях, памяти, таблицах и глобальных переменных — сокращение для полных форм (export ...) и (import ...). Оба варианта компилируются в идентичный бинарник.
;; Inline export on a function
(func (export "add") (param i32 i32) (result i32)
local.get 0
local.get 1
i32.add
)
;; Inline import
(func $log (import "env" "log") (param i32))
;; Inline export on memory
(memory (export "mem") 1)
;; Expanded form (equivalent)
(func $add (param i32 i32) (result i32) ...)
(export "add" (func $add))Сегменты данных
Сегменты данных инициализируют линейную память при инстанцировании (активные) или лениво через memory.init (пассивные). Строки включают escape-последовательности вроде \00 для нулевого терминатора и \n для перевода строки. data.drop освобождает хранилище сегмента после копирования.
;; Initialize memory with bytes at offset 0
(memory 1)
(data (i32.const 0) "Hello, Wasm!\00")
;; Named data segment (active)
(data $msg (i32.const 0) "Hello\00")
;; Passive data segment (used with memory.init)
(data $passive "lazy-loaded bytes")
;; Drop a data segment to free its memory
(data.drop $msg)Конвертация wat2wasm и wasm2wat
WABT (WebAssembly Binary Toolkit) предоставляет wat2wasm (текст в бинарник), wasm2wat (бинарник в текст), wasm-validate и wasm-objdump. Они необходимы для инспекции, отладки и ручного написания модулей Wasm. Форма .wat — для людей; .wasm — то, что выполняют браузеры.
# Install the WebAssembly Binary Toolkit (WABT)
# macOS: brew install wabt
# Ubuntu: apt install wabt
# Convert text -> binary
wat2wasm hello.wat -o hello.wasm
# Convert binary -> text (disassemble)
wasm2wat hello.wasm -o hello.wat
# Validate a .wasm file
wasm-validate hello.wasm
# Print module structure
wasm-objdump -x hello.wasmТипы значений
Базовые типы (i32/i64/f32/f64)
У Wasm всего четыре базовых типа значений: i32, i64, f32, f64. Знаковость целых определяется операцией (например, i32.div_s против i32.div_u), а не типом. Это держит систему типов минимальной и предсказуемой.
;; Wasm has exactly four basic value types:
;; i32 - 32-bit integer
;; i64 - 64-bit integer
;; f32 - 32-bit float
;; f64 - 64-bit float
(func (param i32) (param i64) (param f32) (param f64)
(result f64)
local.get 2 ;; f32
f64.promote_f32
)
;; Integers are signed or unsigned PER OPERATION,
;; not per type. Use i32.add_s / i32.div_u etc.Числовые литералы в WAT
Числовые литералы в WAT поддерживают десятичную, шестнадцатеричную (0x) и двоичную (0b) формы. Float поддерживают научную запись, бесконечность (inf) и NaN. Литералы WAT по умолчанию беззнаковые: отрицательные целые кодируются с ведущим '-'.
;; Integer literals
i32.const 42
i32.const -7
i32.const 0xff ;; hex
i32.const 0b1010 ;; binary
;; Float literals
f64.const 3.14
f64.const 1e10
f64.const -0.0
f64.const inf
f64.const nan
;; 64-bit
i64.const 9007199254740992 ;; 2^53Преобразования типов
Преобразования следуют единой схеме имён: extend (меньше в больше), wrap (больше в меньше), convert (int в float и обратно), reinterpret (побитовое приведение), demote/promote (точность float). Знаковые варианты используют _s, беззнаковые — _u.