Working with externref
You can also browse this source code online and clone the wasmtime repository to run the example locally:
This example shows how to pass opaque host references into and out of WebAssembly using externref.
Wasm Source
(module (table $table (export "table") 10 externref) (global $global (export "global") (mut externref) (ref.null extern)) (func (export "func") (param externref) (result externref) local.get 0 ) ) Host Source
//! Small example of how to use `externref`s. // You can execute this example with `cargo run --example externref` use wasmtime::*; fn main() -> Result<()> { println!("Initializing..."); let mut config = Config::new(); config.wasm_reference_types(true); let engine = Engine::new(&config)?; let mut store = Store::new(&engine, ()); println!("Compiling module..."); let module = Module::from_file(&engine, "examples/externref.wat")?; println!("Instantiating module..."); let instance = Instance::new(&mut store, &module, &[])?; println!("Creating new `externref`..."); let externref = match ExternRef::new(&mut store, "Hello, World!") { Ok(x) => x, Err(e) => match e.downcast::<GcHeapOutOfMemory<&str>>() { Ok(oom) => { let (inner, oom) = oom.take_inner(); store.gc(Some(&oom))?; ExternRef::new(&mut store, inner)? } Err(e) => return Err(e), }, }; assert!( externref .data(&store)? .expect("should have host data") .is::<&'static str>() ); assert_eq!( *externref .data(&store)? .expect("should have host data") .downcast_ref::<&'static str>() .unwrap(), "Hello, World!" ); println!("Touching `externref` table..."); let table = instance.get_table(&mut store, "table").unwrap(); table.set(&mut store, 3, Some(externref).into())?; let elem = table .get(&mut store, 3) .unwrap() // assert in bounds .unwrap_extern() // assert it's an externref table .copied() .unwrap(); // assert the externref isn't null assert!(Rooted::ref_eq(&store, &elem, &externref)?); println!("Touching `externref` global..."); let global = instance.get_global(&mut store, "global").unwrap(); global.set(&mut store, Some(externref).into())?; let global_val = global.get(&mut store).unwrap_externref().copied().unwrap(); assert!(Rooted::ref_eq(&store, &global_val, &externref)?); println!("Calling `externref` func..."); let func = instance.get_typed_func::<Option<Rooted<ExternRef>>, Option<Rooted<ExternRef>>>( &mut store, "func", )?; let ret = func.call(&mut store, Some(externref))?; assert!(ret.is_some()); assert!(Rooted::ref_eq(&store, &ret.unwrap(), &externref)?); println!("GCing within the store..."); store.gc(None)?; println!("Done."); Ok(()) }
/* Example of using `externref` values. You can build using cmake: mkdir build && cd build && cmake .. && \ cmake --build . --target wasmtime-externref */ #include <assert.h> #include <stdio.h> #include <stdlib.h> #include <string.h> #include <wasm.h> #include <wasmtime.h> static void exit_with_error(const char *message, wasmtime_error_t *error, wasm_trap_t *trap); int main() { bool ok = true; // Create a new configuration with Wasm reference types enabled. printf("Initializing...\n"); wasm_config_t *config = wasm_config_new(); assert(config != NULL); wasmtime_config_wasm_reference_types_set(config, true); // Create an *engine*, which is a compilation context, with our configured // options. wasm_engine_t *engine = wasm_engine_new_with_config(config); assert(engine != NULL); // With an engine we can create a *store* which is a group of wasm instances // that can interact with each other. wasmtime_store_t *store = wasmtime_store_new(engine, NULL, NULL); assert(store != NULL); wasmtime_context_t *context = wasmtime_store_context(store); // Read our input file, which in this case is a wasm text file. FILE *file = fopen("examples/externref.wat", "r"); assert(file != NULL); fseek(file, 0L, SEEK_END); size_t file_size = ftell(file); fseek(file, 0L, SEEK_SET); wasm_byte_vec_t wat; wasm_byte_vec_new_uninitialized(&wat, file_size); if (fread(wat.data, file_size, 1, file) != 1) { printf("> Error loading module!\n"); return 1; } fclose(file); // Parse the wat into the binary wasm format wasm_byte_vec_t wasm; wasmtime_error_t *error = wasmtime_wat2wasm(wat.data, wat.size, &wasm); if (error != NULL) exit_with_error("failed to parse wat", error, NULL); wasm_byte_vec_delete(&wat); // Now that we've got our binary webassembly we can compile our module. printf("Compiling module...\n"); wasmtime_module_t *module = NULL; error = wasmtime_module_new(engine, (uint8_t *)wasm.data, wasm.size, &module); wasm_byte_vec_delete(&wasm); if (error != NULL) exit_with_error("failed to compile module", error, NULL); // Instantiate the module. printf("Instantiating module...\n"); wasm_trap_t *trap = NULL; wasmtime_instance_t instance; error = wasmtime_instance_new(context, module, NULL, 0, &instance, &trap); if (error != NULL || trap != NULL) exit_with_error("failed to instantiate", error, trap); printf("Creating new `externref`...\n"); // Create a new `externref` value. // // Note that the NULL here is a finalizer callback, but we don't need one for // this example. wasmtime_externref_t externref; ok = wasmtime_externref_new(context, "Hello, World!", NULL, &externref); assert(ok); // The `externref`'s wrapped data should be the string "Hello, World!". void *data = wasmtime_externref_data(context, &externref); assert(strcmp((char *)data, "Hello, World!") == 0); wasmtime_extern_t item; wasmtime_val_t externref_val; externref_val.kind = WASMTIME_EXTERNREF; externref_val.of.externref = externref; // Lookup the `table` export. printf("Touching `externref` table...\n"); { ok = wasmtime_instance_export_get(context, &instance, "table", strlen("table"), &item); assert(ok); assert(item.kind == WASMTIME_EXTERN_TABLE); // Set `table[3]` to our `externref`. error = wasmtime_table_set(context, &item.of.table, 3, &externref_val); if (error != NULL) exit_with_error("failed to set table", error, NULL); // `table[3]` should now be our `externref`. wasmtime_val_t elem; ok = wasmtime_table_get(context, &item.of.table, 3, &elem); assert(ok); assert(elem.kind == WASMTIME_EXTERNREF); assert(strcmp((char *)wasmtime_externref_data(context, &elem.of.externref), "Hello, World!") == 0); wasmtime_val_unroot(&elem); } printf("Touching `externref` global...\n"); // Lookup the `global` export. { ok = wasmtime_instance_export_get(context, &instance, "global", strlen("global"), &item); assert(ok); assert(item.kind == WASMTIME_EXTERN_GLOBAL); // Set the global to our `externref`. error = wasmtime_global_set(context, &item.of.global, &externref_val); if (error != NULL) exit_with_error("failed to set global", error, NULL); // Get the global, and it should return our `externref` again. wasmtime_val_t global_val; wasmtime_global_get(context, &item.of.global, &global_val); assert(global_val.kind == WASMTIME_EXTERNREF); assert(strcmp((char *)wasmtime_externref_data(context, &global_val.of.externref), "Hello, World!") == 0); wasmtime_val_unroot(&global_val); } printf("Calling `externref` func...\n"); // Lookup the `func` export. { ok = wasmtime_instance_export_get(context, &instance, "func", strlen("func"), &item); assert(ok); assert(item.kind == WASMTIME_EXTERN_FUNC); // And call it! wasmtime_val_t results[1]; error = wasmtime_func_call(context, &item.of.func, &externref_val, 1, results, 1, &trap); if (error != NULL || trap != NULL) exit_with_error("failed to call function", error, trap); // `func` returns the same reference we gave it, so `results[0]` should be // our `externref`. assert(results[0].kind == WASMTIME_EXTERNREF); assert(strcmp((char *)wasmtime_externref_data(context, &results[0].of.externref), "Hello, World!") == 0); wasmtime_val_unroot(&results[0]); } wasmtime_val_unroot(&externref_val); // We can GC any now-unused references to our externref that the store is // holding. printf("GCing within the store...\n"); wasmtime_context_gc(context); // Clean up after ourselves at this point printf("All finished!\n"); wasmtime_store_delete(store); wasmtime_module_delete(module); wasm_engine_delete(engine); return 0; } static void exit_with_error(const char *message, wasmtime_error_t *error, wasm_trap_t *trap) { fprintf(stderr, "error: %s\n", message); wasm_byte_vec_t error_message; if (error != NULL) { wasmtime_error_message(error, &error_message); wasmtime_error_delete(error); } else { wasm_trap_message(trap, &error_message); wasm_trap_delete(trap); } fprintf(stderr, "%.*s\n", (int)error_message.size, error_message.data); wasm_byte_vec_delete(&error_message); exit(1); } #include <fstream> #include <iostream> #include <sstream> #include <wasmtime.hh> using namespace wasmtime; std::string readFile(const char *name) { std::ifstream watFile; watFile.open(name); std::stringstream strStream; strStream << watFile.rdbuf(); return strStream.str(); } int main() { std::cout << "Initializing...\n"; Engine engine; Store store(engine); std::cout << "Compiling module...\n"; auto wat = readFile("examples/externref.wat"); Module module = Module::compile(engine, wat).unwrap(); std::cout << "Instantiating module...\n"; Instance instance = Instance::create(store, module, {}).unwrap(); ExternRef externref(store, std::string("Hello, world!")); std::any &data = externref.data(store); std::cout << "externref data: " << std::any_cast<std::string>(data) << "\n"; std::cout << "Touching `externref` table..\n"; Table table = std::get<Table>(*instance.get(store, "table")); table.set(store, 3, externref).unwrap(); ExternRef val = *table.get(store, 3)->externref(); std::cout << "externref data: " << std::any_cast<std::string>(val.data(store)) << "\n"; std::cout << "Touching `externref` global..\n"; Global global = std::get<Global>(*instance.get(store, "global")); global.set(store, externref).unwrap(); val = *global.get(store).externref(); std::cout << "externref data: " << std::any_cast<std::string>(val.data(store)) << "\n"; std::cout << "Calling `externref` func..\n"; Func func = std::get<Func>(*instance.get(store, "func")); auto results = func.call(store, {externref}).unwrap(); val = *results[0].externref(); std::cout << "externref data: " << std::any_cast<std::string>(val.data(store)) << "\n"; std::cout << "Running a gc..\n"; if (!store.context().gc()) { std::cerr << "> Error while collecting garbage\n"; return 1; } return 0; }