Module fuel 

Fuel for work done by host functions. Wasm instructions burn fuel on their own; a host function charges for its work here, from the same budget, so that fuel bounds the CPU a program spends wherever it spends it.

One fuel is roughly the cost of one interpreted Wasm instruction, about 2.5 ns. Host work is priced by the native time it takes, through a small set of cost classes: each class is a rate per unit of work, and a host function charges CALL plus the classes that describe what it does with the sizes it knows. The rates are placeholders until SUB-1270 measures them; plans/sub-1269-host-fuel-costs.md gives the formula of every host function.

Charges are batched: a charge is refused before the work when the budget is short, but the engine’s fuel is only lowered once HOST_FUEL_BATCH units have accumulated and Wasm has burned more than that since the last application, because set_fuel restarts the engine’s async yield countdown (RuntimeConfig::async_yield_fuel, as in wasmtime) and a loop calling a host function every few instructions would otherwise never yield. The engine may therefore run past the budget by what is pending before Wasm fuel runs out, at most HOST_FUEL_PENDING_CAP; usage reporting clamps to the budget.

Structs

Rate

Fuel per unit of work, as fuel units for every per units of work, so a class worth less than one fuel per unit still charges: the cost rounds up, and no non-empty work is free.

Constants

CALL

Flat charge of every host call; an O(1) host function costs this alone. CALL, TZ and GATE are single-shot amounts for charge_host_fuel; the Rates below scale with a size and go through charge.

COPY

memcpy-like movement of code units or bytes.

ELEM

Per element, entry or field touched, boxed or allocated as a GC value.

GATE

One capability check.

HASH

Cryptographic hashing per byte.

HOST_FUEL_BATCH

Host charges accumulate on the store and are applied to the engine once they reach this many units and Wasm has burned this much since the last application. It must not be below RuntimeConfig::async_yield_fuel: each application restarts the yield countdown, and the countdown needs a full interval between applications.

HOST_FUEL_PENDING_CAP

Pending charges are applied regardless once they reach this, which bounds how far past its budget a run can get before Wasm fuel runs out. Such an application does restart the yield countdown, so a loop that charges this much between yields yields only on the deadline.

IO

Bytes sent, received, read or written; waiting costs nothing.

PARSE

Per byte of parsing or formatting that builds structure (JSON, URLs, numbers, dates, diffs).

REGEX

Regex matching per byte of haystack. The engine is the regex crate: no backtracking, so the worst case is the program size times the haystack, and the program size is capped at compile time.

REGEX_COMPILE

Compiling a regex, on top of PARSE of its source: the program it builds is bounded by a size cap, not by the source length.

SCAN

Per unit read, compared, hashed or transformed with simple logic, including UTF-8/UTF-16 conversion.

SYSCALL

One filesystem metadata operation (open, stat, readdir entry, rename, …).

TZ

One time-zone resolution.

Functions

bigint_product_cost

Multiplication, division or radix conversion of big integers of a and b limbs: a limb operation per limb pair while the operands are small, then, once the library switches to Karatsuba and Toom-3, close to linear in the larger operand. A placeholder shape until SUB-1270 measures it.

charge

Charges n units of work at rate, before the work.

charge_call

Charges the flat per-call cost.

charge_host_fuel

Charges units of host work against the run’s fuel, before the work.

settle

Charges units for work that followed an effect: a response received, a file written, a completion returned. The effect has happened and its result is in hand, so the charge never refuses: a short budget is taken to zero, the call completes, and the run stops at the next fuel check.

settle_host_fuel

settle for an amount of fuel.

sort_cost

The host overhead of sorting n elements: ELEM per comparison and move, n·log2(n) of them. Comparators and key conversions charge themselves.