From c9114ee596e21671674c6f16303869f3bb03a552 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bastian=20K=C3=B6cher?= Date: Mon, 11 Nov 2019 23:54:46 +0100 Subject: [PATCH] Fix runtime interface docs and remove accidentally added file --- core/runtime-interface/proc-macro/src/lib.rs | 7 +- core/sr-api/lib.rs | 190 ------------------- 2 files changed, 6 insertions(+), 191 deletions(-) delete mode 100644 core/sr-api/lib.rs diff --git a/core/runtime-interface/proc-macro/src/lib.rs b/core/runtime-interface/proc-macro/src/lib.rs index febc388c77b17..991fab7569388 100644 --- a/core/runtime-interface/proc-macro/src/lib.rs +++ b/core/runtime-interface/proc-macro/src/lib.rs @@ -120,9 +120,14 @@ mod utils; /// extern "C" { /// /// Every function is exported as `ext_TRAIT_NAME_FUNCTION_NAME_version_VERSION`. /// /// +/// /// `TRAIT_NAME` is converted into snake case. +/// /// /// /// The type for each argument of the exported function depends on /// /// `::FFIType`. -/// pub fn ext_Interface_call_some_complex_code_version_1(data: u64); +/// /// +/// /// `data` holds the pointer and the length to the `[u8]` slice. +/// pub fn ext_Interface_call_some_complex_code_version_1(data: u64) -> u64; +/// /// `optional` holds the pointer and the length of the encoded value. /// pub fn ext_Interface_set_or_clear_version_1(optional: u64); /// } /// } diff --git a/core/sr-api/lib.rs b/core/sr-api/lib.rs deleted file mode 100644 index 0fa0545daef2f..0000000000000 --- a/core/sr-api/lib.rs +++ /dev/null @@ -1,190 +0,0 @@ -// Copyright 2018-2019 Parity Technologies (UK) Ltd. -// This file is part of Substrate. - -// Substrate is free software: you can redistribute it and/or modify -// it under the terms of the GNU General Public License as published by -// the Free Software Foundation, either version 3 of the License, or -// (at your option) any later version. - -// Substrate is distributed in the hope that it will be useful, -// but WITHOUT ANY WARRANTY; without even the implied warranty of -// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -// GNU General Public License for more details. - -// You should have received a copy of the GNU General Public License -// along with Substrate. If not, see . - -//! All the functionality required for declaring and implementing runtime apis. - -#[doc(hidden)] -#[cfg(feature = "std")] -pub use state_machine::{OverlayedChanges, StorageProof}; -#[doc(hidden)] -#[cfg(feature = "std")] -pub use primitives::NativeOrEncoded; -#[doc(hidden)] -#[cfg(not(feature = "std"))] -pub use primitives::to_substrate_wasm_fn_return_value; -#[doc(hidden)] -pub use sr_primitives::{ - traits::{ - Block as BlockT, GetNodeBlockType, GetRuntimeBlockType, - Header as HeaderT, ApiRef, RuntimeApiInfo, Hash as HashT, - }, - generic::BlockId, transaction_validity::TransactionValidity, -}; -#[doc(hidden)] -pub use primitives::{offchain, ExecutionContext}; -#[doc(hidden)] -pub use runtime_version::{ApiId, RuntimeVersion, ApisVec, create_apis_vec}; -#[doc(hidden)] -pub use rstd::{slice, mem}; -#[cfg(feature = "std")] -use rstd::result; -#[doc(hidden)] -pub use codec::{Encode, Decode}; -#[cfg(feature = "std")] -use crate::error; -use sr_api_macros::decl_runtime_apis; -use primitives::OpaqueMetadata; -#[cfg(feature = "std")] -use std::{panic::UnwindSafe, cell::RefCell, rc::Rc}; -#[cfg(feature = "std")] -use primitives::Hasher as HasherT; - -#[cfg(feature = "std")] -/// A type that records all accessed trie nodes and generates a proof out of it. -pub type ProofRecorder = state_machine::ProofRecorder< - <<<::Header as HeaderT>::Hashing as HashT>::Hasher as HasherT>::Out ->; - -/// Something that can be constructed to a runtime api. -#[cfg(feature = "std")] -pub trait ConstructRuntimeApi> { - /// The actual runtime api that will be constructed. - type RuntimeApi; - - /// Construct an instance of the runtime api. - fn construct_runtime_api<'a>(call: &'a C) -> ApiRef<'a, Self::RuntimeApi>; -} - -/// An extension for the `RuntimeApi`. -#[cfg(feature = "std")] -pub trait ApiExt { - /// The given closure will be called with api instance. Inside the closure any api call is - /// allowed. After doing the api call, the closure is allowed to map the `Result` to a - /// different `Result` type. This can be important, as the internal data structure that keeps - /// track of modifications to the storage, discards changes when the `Result` is an `Err`. - /// On `Ok`, the structure commits the changes to an internal buffer. - fn map_api_result result::Result, R, E>( - &self, - map_call: F - ) -> result::Result where Self: Sized; - - /// Checks if the given api is implemented and versions match. - fn has_api( - &self, - at: &BlockId - ) -> error::Result where Self: Sized { - self.runtime_version_at(at).map(|v| v.has_api::()) - } - - /// Check if the given api is implemented and the version passes a predicate. - fn has_api_with bool>( - &self, - at: &BlockId, - pred: P, - ) -> error::Result where Self: Sized { - self.runtime_version_at(at).map(|v| v.has_api_with::(pred)) - } - - /// Returns the runtime version at the given block id. - fn runtime_version_at(&self, at: &BlockId) -> error::Result; - - /// Start recording all accessed trie nodes for generating proofs. - fn record_proof(&mut self); - - /// Extract the recorded proof. - /// This stops the proof recording. - fn extract_proof(&mut self) -> Option; -} - -/// Before calling any runtime api function, the runtime need to be initialized -/// at the requested block. However, some functions like `execute_block` or -/// `initialize_block` itself don't require to have the runtime initialized -/// at the requested block. -/// -/// `call_api_at` is instructed by this enum to do the initialization or to skip -/// it. -#[cfg(feature = "std")] -#[derive(Clone, Copy)] -pub enum InitializeBlock<'a, Block: BlockT> { - /// Skip initializing the runtime for a given block. - /// - /// This is used by functions who do the initialization by themself or don't - /// require it. - Skip, - /// Initialize the runtime for a given block. - /// - /// If the stored `BlockId` is `Some(_)`, the runtime is currently initialized - /// at this block. - Do(&'a RefCell>>), -} - -/// Something that can call into the runtime at a given block. -#[cfg(feature = "std")] -pub trait CallRuntimeAt { - /// Calls the given api function with the given encoded arguments at the given block - /// and returns the encoded result. - fn call_api_at< - 'a, - R: Encode + Decode + PartialEq, - NC: FnOnce() -> result::Result + UnwindSafe, - C: Core, - >( - &self, - core_api: &C, - at: &BlockId, - function: &'static str, - args: Vec, - changes: &RefCell, - initialize_block: InitializeBlock<'a, Block>, - native_call: Option, - context: ExecutionContext, - recorder: &Option>>>, - ) -> error::Result>; - - /// Returns the runtime version at the given block. - fn runtime_version_at(&self, at: &BlockId) -> error::Result; -} - -decl_runtime_apis! { - /// The `Core` api trait that is mandatory for each runtime. - #[core_trait] - #[api_version(2)] - pub trait Core { - /// Returns the version of the runtime. - fn version() -> RuntimeVersion; - /// Execute the given block. - #[skip_initialize_block] - fn execute_block(block: Block); - /// Initialize a block with the given header. - #[renamed("initialise_block", 2)] - #[skip_initialize_block] - #[initialize_block] - fn initialize_block(header: &::Header); - } - - /// The `Metadata` api trait that returns metadata for the runtime. - pub trait Metadata { - /// Returns the metadata of a runtime. - fn metadata() -> OpaqueMetadata; - } - - /// The `TaggedTransactionQueue` api trait for interfering with the new transaction queue. - pub trait TaggedTransactionQueue { - /// Validate the given transaction. - fn validate_transaction(tx: ::Extrinsic) -> TransactionValidity; - } -} -