Skip to content

c_api.md

Latest commit

 

History

History
74 lines (59 loc) · 5.36 KB

c_api.md

File metadata and controls

74 lines (59 loc) · 5.36 KB
Raw

C API reference (wasm-c-api)

zwasm implements the standard wasm-c-api so a C host that drives any wasm-c-api runtime (wasmtime, wasmer, …) drives zwasm unchanged. Three headers in include/:

Header Origin Status
wasm.h Upstream WebAssembly/wasm-c-api, vendored read-only (ADR-0004) Complete — every declared extern function is implemented (293/293; scripts/capi_surface_gap.sh enforces gap=0)
wasi.h Hand-authored project extension (ADR-0005) WASI 0.1 host-setup (zwasm_wasi_config_*, zwasm_store_set_wasi) — no canonical upstream wasi.h exists
zwasm.h Hand-authored project extension (ADR-0179 #3a-4) Instance sandboxing setters (fuel / memory cap / interrupt) + zwasm_trap_kind + per-instance engine selection (zwasm_instance_new_ex) + zwasm_instance_get_func — see below

The header IS the reference — wasm.h is the upstream standard documented at https://github.com/WebAssembly/wasm-c-api. This page maps the families to zwasm specifics.

Standard surface (wasm.h)

Full coverage of the wasm-c-api families:

  • Lifecycle: wasm_engine_new / wasm_store_new / wasm_module_new (parse + validate) / wasm_module_validate / wasm_instance_new / the _delete for each.
  • Externals: wasm_func_* (incl. host callbacks + wasm_func_call), wasm_global_get/_set, wasm_table_get/_set/_grow/_size, wasm_memory_data/_size/_grow.
  • Types: wasm_*type_* (functype / globaltype / tabletype / memorytype / valtype / externtype / importtype / exporttype) + the tagtype family (EH).
  • Values + vectors: wasm_val_*, wasm_*_vec_new/_copy/_delete.
  • Traps + frames: wasm_trap_*, wasm_frame_*.
  • Refs + sharing: wasm_ref_* (_same/_as_*/_copy), host_info accessors, wasm_module_serialize/_deserialize/_share/_obtain.

Residual semantic limits (functions exist + behave honestly, not link-stubbed): wasm_val of.ref = raw payload (D-269); standalone / instance / foreign _copy → null (D-253-D); serialize = source bytes, no AOT cache (D-271). Audit: .dev/c_api_surface_audit_2026-06-04.md.

WASI host-setup (wasi.h)

A C host that already drives wasm.h configures WASI via zwasm_wasi_config_new() → zwasm_wasi_config_set_args / inherit_stdio / … → zwasm_store_set_wasi(store, cfg) (takes ownership). See the worked example in include/wasi.h and docs/examples/c_host/.

zwasm.h extensions

Instance-level budget setters (ADR-0179 #3a-4) mirroring the Zig facade — post-instantiate and re-armable mid-workload (v1's config-level zwasm_config_set_* shape was deliberately rejected). All null-tolerant.

Engine selection. Stock wasm_instance_new builds an .auto-engine instance (JIT where supported, interpreter otherwise). To force the engine from C, use zwasm_instance_new_ex(store, module, imports, trap_out, engine_kind) with ZWASM_ENGINE_AUTO / ZWASM_ENGINE_JIT / ZWASM_ENGINE_INTERP. zwasm_instance_get_func(instance, idx) fetches an export function by index (caller owns the result → release with wasm_func_delete).

Function Effect
zwasm_instance_set_fuel(i, n) / zwasm_instance_disable_fuel(i) deterministic budget; exhaustion traps all fuel consumed (kind 17). Interp units = instructions
zwasm_instance_fuel_remaining(i, &out) remaining budget; returns false when unmetered
zwasm_instance_set_memory_pages_limit(i, p) / …_clear_…(i) host ceiling below the declared max; memory.grow past it returns the spec -1
zwasm_instance_interrupt(i) / zwasm_instance_clear_interrupt(i) cooperative cancel/timeout from any thread; traps interrupted (kind 16) at the next poll
zwasm_trap_kind(trap) machine-readable trap kind beside wasm.h's message-only surface (ZWASM_TRAP_INTERRUPTED/ZWASM_TRAP_OUT_OF_FUEL macros); -1 on NULL

Not shipped (zwasm.h residuals)

Allocator injection and the kind-less zwasm_func_call_fast hot path remain unimplemented (evaluated-on-demand, in keeping with the lightweight design).