Struct Linker

pub struct Linker {
    extern_vals: BTreeMap<ImportKey, ExternVal>,
    pub(crate) store_id: Option<StoreId>,
}

A linker used to link a module’s imports against extern values previously defined in this Linker context.

Manual Instantiation vs. Instantiation through Linker

Traditionally, module instances are instantiated via the method Store::module_instantiate_unchecked, which is part of the official Embedder API defined by the specification. However, this method accepts a list of extern values as an argument. Therefore, if the user wants to manually perform linking they have to figure out the imports of their module, then gather the correct extern values, and finally call the instantiation method.

This process of manual linking is very tedious and error-prone, which is why the Linker exists. It builds on top of the original instantiation method with Linker::module_instantiate_unchecked. Internally this method performs name resolution and then calls the original instantiation. Name resolution is performed on all extern values which were previously defined in the current context.

Extern values

An extern value is represented as a ExternVal. It contains an address to some store-allocated instance. In a linker context, every external value is stored in map with a unique key (module name, name). To define new extern value in some linker context, use Linker::define_unchecked or Linker::define_module_instance_unchecked.

Relationship with Store

There is a N-to-1 relationship between the Linker and the Store. This means that multiple linkers can be used with the same store, while every linker may be used only with one specific store.

Due to performance reasons, this bookkeeping is not done by the Linker itself. Instead it is the user’s responsibility to uphold this requirement.

Fields

extern_vals: BTreeMap<ImportKey, ExternVal>

All extern values in the current linker context by their import keys.

It is guaranteed that the addresses of all extern values belong to the same Store.

store_id: Option<StoreId>

This is for the checked API which makes sure that all objects used originate from the same Store.

Initially the store id is None. Only when a store-specific object or a Store itself is used with a checked method, is this field set. Once initialized it is never written to again.

Implementations

impl Linker

pub fn define( &mut self, module_name: String, name: String, extern_val: StoredExternVal, ) -> Result<(), RuntimeError>

This is a safe variant of Linker::define_unchecked.

pub fn define_module_instance<T: Config>( &mut self, store: &Store<'_, T>, module_name: String, module: Stored<ModuleAddr>, ) -> Result<(), RuntimeError>

This is a safe variant of Linker::define_module_instance_unchecked.

pub fn get( &self, module_name: String, name: String, ) -> Result<StoredExternVal, RuntimeError>

This is a safe variant of Linker::get_unchecked.

Interaction with unchecked API

This method is able to find externs defined through the unchecked define methods. However, for this to work, at least one of the following methods must have been called successfully: Linker::define, Linker::define_module_instance, Linker::module_instantiate. Otherwise, this method may spuriously return an error.

Therefore, it is advised against to mix the unchecked and checked API for a single Linker instance.

Errors

• RuntimeError::LinkerNotYetAssociatedWithStoreId
• RuntimeError::UnableToResolveExternLookup

pub fn instantiate_pre( &self, validation_info: &ValidationInfo<'_>, ) -> Result<Vec<StoredExternVal>, RuntimeError>

This is a safe variant of Linker::instantiate_pre_unchecked.

Interaction with unchecked API

See Linker::get

Errors

• RuntimeError::LinkerNotYetAssociatedWithStoreId
• RuntimeError::UnableToResolveExternLookup

pub fn module_instantiate<'b, T: Config>( &mut self, store: &mut Store<'b, T>, validation_info: &ValidationInfo<'b>, maybe_fuel: Option<u32>, ) -> Result<StoredInstantiationOutcome, RuntimeError>

This is a safe variant of Linker::module_instantiate_unchecked.

impl Linker

pub fn new() -> Self

Creates a new Linker that is not yet associated to any specific Store.

pub fn define_unchecked( &mut self, module_name: String, name: String, extern_val: ExternVal, ) -> Result<(), RuntimeError>

Defines a new extern value in the current Linker context.

Safety

It must be made sure that this Linker is only used with one specific Store and addresses that belong to that store.

pub fn define_module_instance_unchecked<T: Config>( &mut self, store: &Store<'_, T>, module_name: String, module: ModuleAddr, ) -> Result<(), RuntimeError>

Defines all exports of some module instance as extern values in the current Linker.

Safety

It must be guaranteed that this Linker is only ever used with one specific Store and that the given ModuleAddr belongs to this store.

pub fn get_unchecked( &self, module_name: String, name: String, ) -> Option<ExternVal>

Tries to get some extern value by its module name and name.

It is guaranteed that the address contained by the returned ExternVal is part of the Store used with this Linker.

pub fn instantiate_pre_unchecked( &self, validation_info: &ValidationInfo<'_>, ) -> Result<Vec<ExternVal>, RuntimeError>

Performs initial linking of a ValidationInfo’s imports producing a list of extern values usable with Store::module_instantiate_unchecked.

A note on type checking

This method does not perform type checking on the extern values. Therefore, using the returned list of extern values may still fail when trying to instantiate a module with it.

Safety

It must be guaranteed that this Linker is only ever used with one specific Store.

pub fn module_instantiate_unchecked<'b, T: Config>( &self, store: &mut Store<'b, T>, validation_info: &ValidationInfo<'b>, maybe_fuel: Option<u32>, ) -> Result<InstantiationOutcome, RuntimeError>

Variant of Store::module_instantiate_unchecked with automatic name resolution in the current Linker context.

Safety

It must be guaranteed that this Linker is only ever used with one specific Store.

Trait Implementations

impl Clone for Linker

fn clone(&self) -> Linker

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Default for Linker

fn default() -> Linker

Returns the “default value” for a type.