Module hdi::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 HDI 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 HDI 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.

Functions

Type Definitions

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