はじめに
JS での Wasm のロード
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 の Module と Instance
WebAssembly.Module はコンパイル済みで状態を持たない表現です — 複数のインスタンスで安全に再利用できます。WebAssembly.Instance は実行時の状態(memory、globals)を保持します。1 回コンパイルして何度もインスタンス化するのは、並列ワーカーの生成に効率的です。
// 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、exceptions、threads、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;ストリーミング vs 非ストリーミング
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/wasmWasm のマジックナンバーとヘッダー
Wasm バイナリのマジックナンバーは ASCII 文字列の '\0asm' で、その後に 4 バイトのリトルエンディアンのバージョンが続きます。このヘッダーで、コンパイル前にファイルが 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 アプリ: モジュールは JS から 'log' 関数をインポートし、それを呼ぶ '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 テキスト形式
module と S 式
WAT(WebAssembly Text 形式)は Wasm のテキスト表現です。すべてが (module ...) の S 式で包まれます。命令はスタックベースの順で書きます: オペランドを先にプッシュし、その後に演算が消費します。
;; 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 は 2 つのコメント形式をサポートします: ';;' は 1 行、'(; ... ;)' はブロックコメントです。ブロックコメントはネストでき複数行にまたがれます — 開発中にコードの塊を無効化するのに便利です。
;; 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
)インラインの export と import
WAT は関数、memory、table、global にインラインの (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))データセグメント
データセグメントは、インスタンス化時に線形メモリを初期化する(active)か、memory.init で遅延初期化する(passive)ものです。文字列には \00(null 終端)や \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 の基本の値型は 4 つだけです: i32、i64、f32、f64。整数の符号の有無は型ではなく演算で決まります(例: i32.div_s vs 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 の数値リテラルは 10 進、16 進(0x)、2 進(0b)をサポートします。浮動小数点は科学表記、無限大(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(整数↔浮動小数点)、reinterpret(ビットレベルのキャスト)、demote/promote(浮動小数点の精度)。符号付きは _s、符号なしは _u です。
;; Extend i32 to i64
i64.extend_i32_s ;; sign-extend
i64.extend_i32_u ;; zero-extend
;; Wrap i64 to i32
i32.wrap_i64
;; Integer <-> Float
f32.convert_i32_s
f64.convert_i64_u
i32.trunc_f32_s ;; truncate (toward zero)
i32.reinterpret_f32 ;; bit-level reinterpret
;; Demote / promote floats
f32.demote_f64
f64.promote_f32v128 SIMD 型
v128 型は 16 バイトを 1 つの SIMD レジスタに詰め込みます。レーンは i32x4(4×int32)、f32x4(4×float32)、i16x8、i8x16、f64x2 として扱えます。SIMD は 1 命令で複数の値を処理するため、画像/音声/暗号のワークロードを高速化します。
;; SIMD: 128-bit vector type (fixed-width SIMD proposal)
(module
(func (param v128) (result v128)
local.get 0
v128.not ;; bitwise NOT
)
(func (result v128)
v128.const i32x4 1 2 3 4
)
)
;; Vector operations: i32x4, i16x8, i8x16, f32x4, f64x2
v128.const f32x4 1.0 2.0 3.0 4.0
i32x4.add参照型(funcref/externref)
参照型の提案は funcref(関数ポインタ)と externref(不透明なホスト参照)を追加します。externref は強力です: Wasm が JS オブジェクトをコピーもシリアライズもせず保持できます。テーブルと組み合わせると、柔軟なコールバックパターンが可能になります。
;; Reference types proposal adds:
;; funcref - reference to a function (in a table)
;; externref - opaque reference to a host (JS) object
(module
(table 1 funcref)
(func (param externref) (result externref)
local.get 0 ;; pass through a JS object
)
)
;; In JS, externref lets you pass arbitrary objects
;; through Wasm without serialization:
instance.exports.store({ hello: 'world' });関数
関数の定義と呼び出し
関数はコードの基本単位です。call は名前/インデックスで関数を呼びます。引数は呼び出しの前にスタックに積み、結果は関数が戻るときスタックに残ります。スタックは (result ...) の宣言と一致しなければなりません。
(module
(func $add (param $a i32) (param $b i32) (result i32)
local.get $a
local.get $b
i32.add
)
(func $double (param $x i32) (result i32)
local.get $x
local.get $x
i32.add ;; or: i32.const 2 i32.mul
)
(func (export "use")
i32.const 5
i32.const 7
call $add ;; -> 12 on stack
drop
)
)パラメータとローカル変数
パラメータは 0 起点のインデックスを持つ不変のローカルです。宣言したローカル(local $name type)はゼロ初期化され、可変です。local.get、local.set、local.tee(set +スタックに残す)を使います。ローカル変数は memory/global の外では Wasm 唯一の可変ストレージです。
(func $f (param $a i32) (param $b i32) (result i32)
(local $sum i32) ;; mutable local
(local $i i32)
local.get $a
local.get $b
i32.add
local.set $sum ;; store into local
i32.const 0
local.set $i
local.get $sum
)
;; tee: set and keep on stack
local.tee $sum ;; $sum = top; stays on stack複数の戻り値
multi-value 提案により、関数は複数の値を返せ(0 個も受け付け)、2020 年以降すべての主要エンジニアリングでサポートされています。これにより memory 経由の出力パラメータが不要になり、swap/minmax のようなイディオムが自然に書けます。
;; Multi-value: return two i32 values
(func $minmax (param $a i32) (param $b i32) (result i32 i32)
local.get $a
local.get $b
i32.lt_s
if (result i32 i32)
local.get $a
local.get $b
else
local.get $b
local.get $a
end
)
;; Caller receives both on the stack
(func (export "use")
i32.const 3
i32.const 8
call $minmax
;; stack: [min=3, max=8]
drop drop
)再帰
Wasm は直接再帰をサポートします — 関数は自分自身を呼べます。MVP の Wasm には末尾呼び出し最適化がありま せん(tail-call 提案が return_call を追加します)。深い再帰はスタックオーバーフローのリスクがあるため、本番コードでは反復ループが推奨です。
(module
(func $fact (param $n i32) (result i32)
local.get $n
i32.const 1
i32.le_s
if (result i32)
i32.const 1
else
local.get $n
local.get $n
i32.const 1
i32.sub
call $fact ;; recursive call
i32.mul
end
)
(export "factorial" (func $fact))
)インライン export と名前付き呼び出し
関数定義に付けたインラインの (export "name") は、独立した (export ...) 宣言のショートハンドです。call_ref(参照型の提案)は funcref 経由で直接関数を呼び出し、テーブル参照なしで第一級の関数値を可能にします。
(module
;; Inline export on definition
(func $add (export "add") (param i32 i32) (result i32)
local.get 0
local.get 1
i32.add
)
;; call_ref: call via funcref (reference types)
(func $caller (param $f funcref) (param i32) (result i32)
local.get 1
local.get 0
call_ref (param i32) (result i32)
)
)start 関数
モジュールは 1 つの (start $func) 関数を宣言でき、インスタンス化時に自動で実行されます — 初期化に便利です。引数を取らず何も返しません。start 関数はモジュールに 1 つしか許されません。