Crate holochain_wasmer_common

Expand description

Types and helpers shared between holochain_wasmer_host and holochain_wasmer_guest: the WasmError / WasmErrorInner error model, the wasm_error! convenience macro, and the small numeric helpers (merge_usize / split_usize etc) used to pack pointer/length pairs across the host↔guest boundary.

§Cargo features

error-as-host — when constructing a WasmError from a bare String, classify it as WasmErrorInner::Host rather than WasmErrorInner::Guest. Hosts that build error strings should enable this; guests should leave it off. The host crate enables it via its own error-as-host feature.

holochain_serial: unidiomatic way to derive default trait implementations of TryFrom in/out of SerializedBytes
wasm_error: Helper macro for returning an error from a WASM.

SerializedBytes: A Canonical Serialized Bytes representation for data If you have a data structure that needs a canonical byte representation use this Always round-trip through SerializedBytes via. a single TryFrom implementation. This ensures that the internal bytes of SerializedBytes are indeed canonical. The corrolary is that if bytes are NOT wrapped in SerializedBytes we can assume they are NOT canonical. Typically we need a canonical serialization when data is to be handled at the byte level by independently implemented and maintained systems.
UnsafeBytes: UnsafeBytes the only way to implement a custom round trip through bytes for SerializedBytes It is intended to be an internal implementation in TryFrom implementations The assumption is that any code using UnsafeBytes is NOT valid messagepack data This allows us to enforce that all data round-tripping through SerializedBytes is via TryFrom and also allow for custom non-messagepack canonical representations of data types.

Deserialize: A data structure that can be deserialized from any data format supported by Serde.
Serialize: A data structure that can be serialized into any data format supported by Serde.
TryFrom: Simple and safe type conversions that may fail in a controlled way under some circumstances. It is the reciprocal of TryInto.
TryInto: An attempted conversion that consumes self, which may or may not be expensive.

decode
encode
merge_u32
merge_u64
merge_usize: Given 2x u32, return a DoubleUSize merged. Works via a simple bitwise shift to move the pointer to high bits then OR the length into the low bits.
split_u64
split_u128
split_usize: Given 2x merged usize, split out two usize. Performs the inverse of merge_usize.

DoubleUSize
GuestPtr: A WasmSize that points to a position in wasm linear memory that the host and guest are sharing to communicate across function calls.
GuestPtrLen: Enough bits to fit a pointer and length into so we can return it. The externs defined as “C” don’t support multiple return values (unlike wasm). The native Rust support for wasm externs is not stable at the time of writing.
Len: A WasmSize integer that represents the size of bytes to read/write to memory.
WasmSize: Something like usize for wasm. Wasm has a memory limit of 4GB so offsets and lengths fit in u32.