Module hdk::map_extern

source ·
Expand description

Maps a Rust function to an extern that WASM can expose to the Holochain host.

Annotate any compatible function with hdk_extern! to expose it to Holochain as a WASM extern. The map_extern! macro is used internally by the hdk_extern! attribute.

Compatible functions:

  • Have a globally unique name
  • Accept serde::Serialize + std::fmt::Debug input
  • Return Result<O, WasmError> (ExternResult) output where O: serde::Serialize + std::fmt::Debug

This module only defines macros so check the HDK crate root to see more documentation.

A new extern function is created with the same name as the function with the hdk_extern! attribute. The new extern is placed in a child module of the current scope. This new extern is hoisted by WASM to share a global namespace with all other externs so names must be globally unique even if the base function is scoped.

The new extern handles:

  • Extern syntax for Rust
  • Receiving the serialized bytes from the host at a memory pointer specified by the guest
  • Setting the HDK WASM tracing subscriber as the global default
  • Deserializing the input from the host
  • Calling the function annotated with hdk_extern!
  • Serializing the result
  • Converting the serialized result to a memory pointer for the host
  • Error handling for all the above

If you want to do something different to the default you will need to understand and reimplement all the above.


Type Definitions

Every extern must return a WasmError in the case of failure.