wasm-performance

# WebAssembly Performance

Techniques for reducing WASM binary size and maximizing runtime performance.

## When to Activate

- Binary is too large for acceptable load time
- Profiling reveals WASM execution bottlenecks
- Memory usage is growing unexpectedly
- Implementing compute-intensive features in WASM
- Enabling SIMD or multi-threading for heavy workloads
- Reducing JS↔Wasm boundary crossings by batching calls or sharing linear memory directly
- Using `twiggy` or `cargo-bloat` to identify which crate or function is dominating binary size

---

## Binary Size Optimization

### Cargo Profile (highest impact)

```toml
# Cargo.toml
[profile.release]
opt-level = "s"       # Optimize for size (use "z" for minimal size at cost of speed)
lto = true            # Link-time optimization — eliminates dead code across crates
panic = "abort"       # Skip unwinding tables (~50KB savings)
codegen-units = 1     # Single codegen unit — better LTO
strip = true          # Strip debug symbols
```

### wasm-opt (Binaryen)

```bash
# Install
cargo install wasm-opt  # or: brew install binaryen

# Optimize for size after wasm-pack build
wasm-opt -Os -o output.wasm input.wasm

# Optimize for speed
wasm-opt -O3 -o output.wasm input.wasm

# Maximum size reduction (slower, aggressive)
wasm-opt -Oz --enable-mutable-globals -o output.wasm input.wasm

# Enable SIMD optimizations
wasm-opt -O3 --enable-simd -o output.wasm input.wasm

# wasm-pack integrates wasm-opt automatically in release mode
wasm-pack build --release  # runs wasm-opt -O automatically
```

### twiggy — Dependency Size Analyzer

```bash
cargo install twiggy

# What's taking space?
twiggy top target/wasm32-unknown-unknown/release/my_lib.wasm

# Full call graph
twiggy paths target/wasm32-unknown-unknown/release/my_lib.wasm

# Example output:
#  Shallow Bytes │ Shallow % │ Item
# ───────────────┼───────────┼────────────────────
#          81996 ┊    36.10% ┊ "function names" subsection
#          36713 ┊    16.16% ┊ fmt::Display for f64
#          12300 ┊     5.41% ┊ serde::de::Visitor
```

### cargo-bloat — Rust Bloat Detector

```bash
cargo install cargo-bloat

# Find largest functions
cargo bloat --release --target wasm32-unknown-unknown -n 20

# Find largest crates
cargo bloat --release --target wasm32-unknown-unknown --crates
```

### Reducing Dependency Footprint

```toml
# Disable default features you don't need
[dependencies]
serde = { version = "1", default-features = false, features = ["derive"] }
chrono = { version = "0.4", default-features = false, features = ["serde"] }

# Use lighter alternatives for WASM
# Instead of std HashMap (larger): use ahash or a no-std map
```

---

## Runtime Performance

### Avoid JS↔Wasm Boundary Crossings

Every call across the JS/Wasm boundary has overhead. Batch work:

```rust
// BAD: many small calls across the boundary
#[wasm_bindgen]
pub fn process_item(item: u32) -> u32 {
    item * 2 + 1
}

// In JS:
// for (const item of items) result.push(process_item(item));  // N crossings

// GOOD: single call with slice
#[wasm_bindgen]
pub fn process_batch(items: &[u32]) -> Vec<u32> {
    items.iter().map(|&x| x * 2 + 1).collect()
}

// In JS:
// const result = process_batch(new Uint32Array(items));  // 1 crossing
```

### Share Memory Instead of Copying

```rust
use wasm_bindgen::prelude::*;

// Allocate memory in WASM heap
#[wasm_bindgen]
pub fn alloc(size: usize) -> *mut u8 {
    let mut buf: Vec<u8> = Vec::with_capacity(size);
    let ptr = buf.as_mut_ptr();
    std::mem::forget(buf);  // Give ownership to caller
    ptr
}

#[wasm_bindgen]
pub fn dealloc(ptr: *mut u8, size: usize) {
    unsafe { drop(Vec::from_raw_parts(ptr, 0, size)) }
}

// JS: write directly into WASM memory
#[wasm_bindgen]
pub fn process_buffer(ptr: *const u8, len: usize) -> u32 {
    let slice = unsafe { std::slice::from_raw_parts(ptr, len) };
    slice.iter().map(|&b| b as u32).sum()
}
```

```typescript
// Direct memory access from JS
const memory = wasm_instance.memory as WebAssembly.Memory;
const ptr = alloc(data.length);
new Uint8Array(memory.buffer, ptr, data.length).set(data);  // Zero copy
const result = process_buffer(ptr, data.length);
dealloc(ptr, data.length);
```

### SIMD (WebAssembly SIMD)

```rust
// Enable SIMD via target features
// RUSTFLAGS="-C target-feature=+simd128"

use std::arch::wasm32::*;

#[cfg(target_arch = "wasm32")]
pub fn dot_product_simd(a: &[f32], b: &[f32]) -> f32 {
    assert_eq!(a.len(), b.len());
    let mut sum = f32x4_splat(0.0);
    let chunks = a.len() / 4;

    for i in 0..chunks {
        let a_vec = unsafe { v128_load(a.as_ptr().add(i * 4) as *const v128) };
        let b_vec = unsafe { v128_load(b.as_ptr().add(i * 4) as *const v128) };
        sum = f32x4_add(sum, f32x4_mul(a_vec, b_vec));
    }

    let arr: [f32; 4] = unsafe { std::mem::transmute(sum) };
    arr.iter().sum()
}
```

```bash
# Build with SIMD
RUSTFLAGS="-C target-feature=+simd128" wasm-pack build --release

# wasm-opt with SIMD
wasm-opt -O3 --enable-simd output.wasm -o output_simd.wasm
```

### Multi-Threading with SharedArrayBuffer

```rust
// Cargo.toml
[dependencies]
wasm-bindgen-rayon = "1.0"

// lib.rs
use wasm_bindgen_rayon::init_thread_pool;

#[wasm_bindgen]
pub async fn setup_threads() {
    init_thread_pool(4).await;  // 4 web workers
}

#[wasm_bindgen]
pub fn parallel_sum(data: &[f64]) -> f64 {
    use rayon::prelude::*;
    data.par_iter().sum()
}
```

```html
<!-- Required headers for SharedArrayBuffer -->
<meta http-equiv="Cross-Origin-Opener-Policy" content="same-origin">
<meta http-equiv="Cross-Origin-Embedder-Policy" content="require-corp">
```

---

## Memory Management

### Linear Memory Growth

```rust
// Check current memory usage
#[wasm_bindgen]
pub fn memory_usage() -> usize {
    // Returns pages × 64KB
    core::arch::wasm32::memory_size(0) * 64 * 1024
}

// Grow memory explicitly (rarely needed — usually automatic)
#[wasm_bindgen]
pub fn ensure_capacity(bytes: usize) {
    let current = core::arch::wasm32::memory_size(0) * 65536;
    if bytes > current {
        let pages_needed = (bytes - current + 65535) / 65536;
        core::arch::wasm32::memory_grow(0, pages_needed);
    }
}
```

### Avoid Memory Leaks

```rust
// WRONG: forgot to drop → memory leak
#[wasm_bindgen]
pub fn leaky(size: usize) -> *mut u8 {
    let mut v: Vec<u8> = vec![0; size];
    let ptr = v.as_mut_ptr();
    std::mem::forget(v);  // Intentional — but caller must free
    ptr
}

// CORRECT: use Box for single values, provide dealloc
#[wasm_bindgen]
pub fn create_buffer(size: usize) -> *mut u8 {
    Box::into_raw(vec![0u8; size].into_boxed_slice()) as *mut u8
}

#[wasm_bindgen]
pub unsafe fn free_buffer(ptr: *mut u8, size: usize) {
    let _ = Box::from_raw(std::slice::from_raw_parts_mut(ptr, size));
}
```

---

## Profiling

### Chrome DevTools

```javascript
// Enable DWARF debug info for source maps
// wasm-pack build --dev  (dev build with debug info)

// Profile in DevTools:
// 1. Open DevTools → Performance tab
// 2. Enable: Settings → "WebAssembly debugging: Enable DWARF support"
// 3. Record a profile
// 4. In flame chart: Wasm functions appear with Rust source names
```

### console.time in Rust

```rust
use web_sys::console;

#[wasm_bindgen]
pub fn benchmark_process(data: &[u8]) -> u32 {
    console::time_with_label("process");
    let result = expensive_computation(data);
    console::time_end_with_label("process");
    result
}
```

### Counting Operations

```rust
use std::sync::atomic::{AtomicU64, Ordering};
static OPS_COUNT: AtomicU64 = AtomicU64::new(0);

pub fn hot_function(x: u64) -> u64 {
    OPS_COUNT.fetch_add(1, Ordering::Relaxed);
    x * x + x + 1
}

#[wasm_bindgen]
pub fn get_ops_count() -> u64 {
    OPS_COUNT.load(Ordering::Relaxed)
}
```

---

## Size Benchmarks

| Technique | Savings |
|-----------|---------|
| `opt-level = "s"` | 20–40% |
| `lto = true` | 10–30% |
| `panic = "abort"` | ~50KB |
| `wasm-opt -Os` | 10–20% |
| `strip = true` | 20–60% |
| Remove unused features | varies |

**Typical final size for a medium-complexity library:**
- Before optimization: 500KB–2MB
- After all techniques: 50KB–200KB

---

## Loading Strategy by Size

| Binary Size | Strategy |
|-------------|---------|
| < 100KB | Inline as base64 or bundle |
| 100KB–1MB | Streaming instantiation (`WebAssembly.instantiateStreaming`) |
| > 1MB | Lazy load on demand + loading indicator |

```typescript
// Streaming instantiation (most efficient)
const { instance } = await WebAssembly.instantiateStreaming(
  fetch('/assets/my_lib.wasm'),
  importObject
);

// Fallback for servers without correct Content-Type
async function loadWasm(url: string) {
  try {
    return await WebAssembly.instantiateStreaming(fetch(url));
  } catch {
    const bytes = await (await fetch(url)).arrayBuffer();
    return WebAssembly.instantiate(bytes);
  }
}
```

## Reference

- `wasm-patterns` — wasm-bindgen, WASI, Component Model, JS integration
- `rust-patterns` — Rust idioms that affect WASM output
- wasm-opt docs: <https://github.com/WebAssembly/binaryen>
- Rust WASM book: <https://rustwasm.github.io/book/>