Module externref::processor

Available on crate feature processor only.

WASM module processor for externrefs.

WASM modules that use the externref crate need to be processed in order to use externref function args / return types for imported or exported functions that originally used Resources. This module encapsulates processing logic.

More precisely, the processor performs the following steps:

• Parse the custom section with Function declarations and remove this section from the module.
• Replace imported functions from a surrogate module for handling externrefs with local functions.
• Patch signatures and implementations of imported / exported functions so that they use externrefs where appropriate.
• Add an initially empty, unconstrained table with externref elements and optionally export it from the module. The host can use the table to inspect currently used references (e.g., to save / restore WASM instance state).

See crate-level docs for more insights on WASM module setup and processing.

On processing order

⚠ Important. The Processor should run before WASM optimization tools such as wasm-opt. These tools may inline externref-operating functions, which can lead to the processor producing invalid WASM bytecode (roughly speaking, excessively replacing i32s with externrefs). Such inlining can usually be detected by the processor, in which case it will return Error::IncorrectGuard or Error::UnexpectedCall from process().

Optimizing WASM after the processor has an additional advantage in that it can optimize the changes produced by it (optimization is hard, and is best left to the dedicated tools).

Examples

use externref::processor::Processor;

let module: Vec<u8> = // WASM module, e.g., loaded from the file system
let processed: Vec<u8> = Processor::default()
    // Set a hook to be called when a reference is dropped
    .set_drop_fn("test", "drop_ref")
    .process_bytes(&module)?;
// Store or use the processed module...

Structs

• Processor
  WASM module processor encapsulating processing options.

Enums

• Error
  Errors that can occur when processing a WASM module.
• Location
  Location of a Resource: a function argument or a return type.