Struct sc_executor::WasmExecutor

pub struct WasmExecutor<H> { /* private fields */ }

An abstraction over Wasm code executor. Supports selecting execution backend and manages runtime cache.

Implementations

impl<H> WasmExecutor<H>where
    H: HostFunctions,

pub fn new(
    method: WasmExecutionMethod,
    default_heap_pages: Option<u64>,
    max_runtime_instances: usize,
    cache_path: Option<PathBuf>,
    runtime_cache_size: u8
) -> Self

Create new instance.

Parameters

method - Method used to execute Wasm code.

default_heap_pages - Number of 64KB pages to allocate for Wasm execution. Defaults to DEFAULT_HEAP_PAGES if None is provided.

max_runtime_instances - The number of runtime instances to keep in memory ready for reuse.

cache_path - A path to a directory where the executor can place its files for purposes of caching. This may be important in cases when there are many different modules with the compiled execution method is used.

runtime_cache_size - The capacity of runtime cache.

Examples found in repository

src/native_executor.rs (lines 401-407)

	pub fn new(
		fallback_method: WasmExecutionMethod,
		default_heap_pages: Option<u64>,
		max_runtime_instances: usize,
		runtime_cache_size: u8,
	) -> Self {
		let wasm = WasmExecutor::new(
			fallback_method,
			default_heap_pages,
			max_runtime_instances,
			None,
			runtime_cache_size,
		);

		NativeElseWasmExecutor {
			_dummy: Default::default(),
			native_version: D::native_version(),
			wasm,
		}
	}

pub fn allow_missing_host_functions(
    &mut self,
    allow_missing_host_functions: bool
)

Ignore missing function imports if set true.

pub fn with_instance<R, F>(
    &self,
    runtime_code: &RuntimeCode<'_>,
    ext: &mut dyn Externalities,
    f: F
) -> Result<R>where
    F: FnOnce(AssertUnwindSafe<&Arc<dyn WasmModule>>, AssertUnwindSafe<&mut dyn WasmInstance>, Option<&RuntimeVersion>, AssertUnwindSafe<&mut dyn Externalities>) -> Result<Result<R>>,

Execute the given closure f with the latest runtime (based on runtime_code).

The closure f is expected to return Err(_) when there happened a panic! in native code while executing the runtime in Wasm. If a panic! occurred, the runtime is invalidated to prevent any poisoned state. Native runtime execution does not need to report back any panic!.

Safety

runtime and ext are given as AssertUnwindSafe to the closure. As described above, the runtime is invalidated on any panic! to prevent a poisoned state. ext is already implicitly handled as unwind safe, as we store it in a global variable while executing the native runtime.

Examples found in repository

src/native_executor.rs (lines 345-347)

	fn call(
		&self,
		ext: &mut dyn Externalities,
		runtime_code: &RuntimeCode,
		method: &str,
		data: &[u8],
		_use_native: bool,
	) -> (Result<Vec<u8>>, bool) {
		tracing::trace!(
			target: "executor",
			%method,
			"Executing function",
		);

		let result =
			self.with_instance(runtime_code, ext, |_, mut instance, _onchain_version, mut ext| {
				with_externalities_safe(&mut **ext, move || instance.call_export(method, data))
			});
		(result, false)
	}
}

impl<H> RuntimeVersionOf for WasmExecutor<H>
where
	H: HostFunctions,
{
	fn runtime_version(
		&self,
		ext: &mut dyn Externalities,
		runtime_code: &RuntimeCode,
	) -> Result<RuntimeVersion> {
		self.with_instance(runtime_code, ext, |_module, _instance, version, _ext| {
			Ok(version.cloned().ok_or_else(|| Error::ApiError("Unknown version".into())))
		})
	}
}

/// A generic `CodeExecutor` implementation that uses a delegate to determine wasm code equivalence
/// and dispatch to native code when possible, falling back on `WasmExecutor` when not.
pub struct NativeElseWasmExecutor<D>
where
	D: NativeExecutionDispatch,
{
	/// Dummy field to avoid the compiler complaining about us not using `D`.
	_dummy: PhantomData<D>,
	/// Native runtime version info.
	native_version: NativeVersion,
	/// Fallback wasm executor.
	wasm:
		WasmExecutor<ExtendedHostFunctions<sp_io::SubstrateHostFunctions, D::ExtendHostFunctions>>,
}

impl<D: NativeExecutionDispatch> NativeElseWasmExecutor<D> {
	/// Create new instance.
	///
	/// # Parameters
	///
	/// `fallback_method` - Method used to execute fallback Wasm code.
	///
	/// `default_heap_pages` - Number of 64KB pages to allocate for Wasm execution.
	/// 	Defaults to `DEFAULT_HEAP_PAGES` if `None` is provided.
	///
	/// `max_runtime_instances` - The number of runtime instances to keep in memory ready for reuse.
	///
	/// `runtime_cache_size` - The capacity of runtime cache.
	pub fn new(
		fallback_method: WasmExecutionMethod,
		default_heap_pages: Option<u64>,
		max_runtime_instances: usize,
		runtime_cache_size: u8,
	) -> Self {
		let wasm = WasmExecutor::new(
			fallback_method,
			default_heap_pages,
			max_runtime_instances,
			None,
			runtime_cache_size,
		);

		NativeElseWasmExecutor {
			_dummy: Default::default(),
			native_version: D::native_version(),
			wasm,
		}
	}

	/// Ignore missing function imports if set true.
	pub fn allow_missing_host_functions(&mut self, allow_missing_host_functions: bool) {
		self.wasm.allow_missing_host_functions = allow_missing_host_functions
	}
}

impl<D: NativeExecutionDispatch> RuntimeVersionOf for NativeElseWasmExecutor<D> {
	fn runtime_version(
		&self,
		ext: &mut dyn Externalities,
		runtime_code: &RuntimeCode,
	) -> Result<RuntimeVersion> {
		self.wasm.with_instance(runtime_code, ext, |_module, _instance, version, _ext| {
			Ok(version.cloned().ok_or_else(|| Error::ApiError("Unknown version".into())))
		})
	}
}

impl<D: NativeExecutionDispatch> GetNativeVersion for NativeElseWasmExecutor<D> {
	fn native_version(&self) -> &NativeVersion {
		&self.native_version
	}
}

impl<D: NativeExecutionDispatch + 'static> CodeExecutor for NativeElseWasmExecutor<D> {
	type Error = Error;

	fn call(
		&self,
		ext: &mut dyn Externalities,
		runtime_code: &RuntimeCode,
		method: &str,
		data: &[u8],
		use_native: bool,
	) -> (Result<Vec<u8>>, bool) {
		tracing::trace!(
			target: "executor",
			function = %method,
			"Executing function",
		);

		let mut used_native = false;
		let result = self.wasm.with_instance(
			runtime_code,
			ext,
			|_, mut instance, onchain_version, mut ext| {
				let onchain_version =
					onchain_version.ok_or_else(|| Error::ApiError("Unknown version".into()))?;

				let can_call_with =
					onchain_version.can_call_with(&self.native_version.runtime_version);

				if use_native && can_call_with {
					tracing::trace!(
						target: "executor",
						native = %self.native_version.runtime_version,
						chain = %onchain_version,
						"Request for native execution succeeded",
					);

					used_native = true;
					Ok(with_externalities_safe(&mut **ext, move || D::dispatch(method, data))?
						.ok_or_else(|| Error::MethodNotFound(method.to_owned())))
				} else {
					if !can_call_with {
						tracing::trace!(
							target: "executor",
							native = %self.native_version.runtime_version,
							chain = %onchain_version,
							"Request for native execution failed",
						);
					}

					with_externalities_safe(&mut **ext, move || instance.call_export(method, data))
				}
			},
		);
		(result, used_native)
	}

Trait Implementations

impl<H> Clone for WasmExecutor<H>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<H> CodeExecutor for WasmExecutor<H>where
    H: HostFunctions,

type Error = Error

Externalities error type.

fn call(
    &self,
    ext: &mut dyn Externalities,
    runtime_code: &RuntimeCode<'_>,
    method: &str,
    data: &[u8],
    _use_native: bool
) -> (Result<Vec<u8>>, bool)

Call a given method in the runtime. Returns a tuple of the result (either the output data or an execution error) together with a bool, which is true if native execution was used.

impl<H> ReadRuntimeVersion for WasmExecutor<H>where
    H: HostFunctions,

fn read_runtime_version(
    &self,
    wasm_code: &[u8],
    ext: &mut dyn Externalities
) -> Result<Vec<u8>, String>

Reads the runtime version information from the given wasm code.

impl<H> RuntimeVersionOf for WasmExecutor<H>where
    H: HostFunctions,

fn runtime_version(
    &self,
    ext: &mut dyn Externalities,
    runtime_code: &RuntimeCode<'_>
) -> Result<RuntimeVersion>

Extract RuntimeVersion of the given runtime_code.