From 4f7e36e0726f6a98c0c8ee340023c5387a696583 Mon Sep 17 00:00:00 2001 From: Sergei Pepyakin Date: Fri, 6 Sep 2019 23:08:08 +0200 Subject: [PATCH] Update docs for the wasm executor crate (#3569) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Grammar. * Update docs for wasm executor. * Update core/executor/src/lib.rs Co-Authored-By: André Silva --- substrate/core/executor/src/lib.rs | 19 ++++++++++--------- .../core/executor/src/native_executor.rs | 8 ++++++-- substrate/core/executor/src/wasm_executor.rs | 5 ++++- substrate/core/executor/src/wasm_utils.rs | 2 +- substrate/core/state-machine/src/lib.rs | 4 ++-- 5 files changed, 23 insertions(+), 15 deletions(-) diff --git a/substrate/core/executor/src/lib.rs b/substrate/core/executor/src/lib.rs index 065de451c1..684200519e 100644 --- a/substrate/core/executor/src/lib.rs +++ b/substrate/core/executor/src/lib.rs @@ -14,16 +14,17 @@ // You should have received a copy of the GNU General Public License // along with Substrate. If not, see . -//! Temporary crate for contracts implementations. +//! A crate that provides means of executing/dispatching calls into the runtime. //! -//! This will be replaced with WASM contracts stored on-chain. -//! ** NOTE *** -//! This is entirely deprecated with the idea of a single-module Wasm module for state transition. -//! The dispatch table should be replaced with the specific functions needed: -//! - execute_block(bytes) -//! - init_block(PrevBlock?) -> InProgressBlock -//! - add_transaction(InProgressBlock) -> InProgressBlock -//! It is left as is for now as it might be removed before this is ever done. +//! There are a few responsibilities of this crate at the moment: +//! +//! - It provides an implementation of a common entrypoint for calling into the runtime, both +//! wasm and compiled. +//! - It defines the environment for the wasm execution, namely the host functions that are to be +//! provided into the wasm runtime module. +//! - It also provides the required infrastructure for executing the current wasm runtime (specified +//! by the current value of `:code` in the provided externalities), i.e. interfacing with +//! wasm engine used, instance cache. #![warn(missing_docs)] #![recursion_limit="128"] diff --git a/substrate/core/executor/src/native_executor.rs b/substrate/core/executor/src/native_executor.rs index 1ebf7f3146..616b9f8c6d 100644 --- a/substrate/core/executor/src/native_executor.rs +++ b/substrate/core/executor/src/native_executor.rs @@ -47,9 +47,13 @@ pub fn with_native_environment(ext: &mut dyn Externalities, ::runtime_io::with_externalities(ext, move || safe_call(f)) } -/// Delegate for dispatching a CodeExecutor call to native code. +/// Delegate for dispatching a CodeExecutor call. +/// +/// By dispatching we mean that we execute a runtime function specified by it's name. pub trait NativeExecutionDispatch: Send + Sync { - /// Dispatch a method and input data to be executed natively. + /// Dispatch a method in the runtime. + /// + /// If the method with the specified name doesn't exist then `Err` is returned. fn dispatch(ext: &mut dyn Externalities, method: &str, data: &[u8]) -> Result>; /// Provide native runtime version. diff --git a/substrate/core/executor/src/wasm_executor.rs b/substrate/core/executor/src/wasm_executor.rs index b22fe3d363..d8fd41ab7f 100644 --- a/substrate/core/executor/src/wasm_executor.rs +++ b/substrate/core/executor/src/wasm_executor.rs @@ -14,7 +14,10 @@ // You should have received a copy of the GNU General Public License // along with Substrate. If not, see . -//! Rust implementation of Substrate contracts. +//! Wasm interface module. +//! +//! This module defines and implements the wasm part of Substrate Host Interface and provides +//! an interface for calling into the wasm runtime. use std::{collections::HashMap, convert::TryFrom, str}; use tiny_keccak; diff --git a/substrate/core/executor/src/wasm_utils.rs b/substrate/core/executor/src/wasm_utils.rs index 80ef376df5..8f38499321 100644 --- a/substrate/core/executor/src/wasm_utils.rs +++ b/substrate/core/executor/src/wasm_utils.rs @@ -14,7 +14,7 @@ // You should have received a copy of the GNU General Public License // along with Substrate. If not, see . -//! Rust implementation of Substrate contracts. +//! Utilities for defining the wasm host environment. use wasmi::{ValueType, RuntimeValue}; use wasmi::nan_preserving_float::{F32, F64}; diff --git a/substrate/core/state-machine/src/lib.rs b/substrate/core/state-machine/src/lib.rs index 70a7f3b146..0ffac5e688 100644 --- a/substrate/core/state-machine/src/lib.rs +++ b/substrate/core/state-machine/src/lib.rs @@ -226,10 +226,10 @@ pub trait Externalities { /// Clear an entire child storage. fn kill_child_storage(&mut self, storage_key: ChildStorageKey); - /// Clear storage entries which keys are start with the given prefix. + /// Clear storage entries which keys start with the given prefix. fn clear_prefix(&mut self, prefix: &[u8]); - /// Clear child storage entries which keys are start with the given prefix. + /// Clear child storage entries which keys start with the given prefix. fn clear_child_prefix(&mut self, storage_key: ChildStorageKey, prefix: &[u8]); /// Set or clear a storage entry (`key`) of current contract being called (effective immediately).