sp_io/lib.rs
1// This file is part of Substrate.
2
3// Copyright (C) Parity Technologies (UK) Ltd.
4// SPDX-License-Identifier: Apache-2.0
5
6// Licensed under the Apache License, Version 2.0 (the "License");
7// you may not use this file except in compliance with the License.
8// You may obtain a copy of the License at
9//
10// http://www.apache.org/licenses/LICENSE-2.0
11//
12// Unless required by applicable law or agreed to in writing, software
13// distributed under the License is distributed on an "AS IS" BASIS,
14// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15// See the License for the specific language governing permissions and
16// limitations under the License.
17
18//! # Substrate Primitives: IO
19//!
20//! This crate contains interfaces for the runtime to communicate with the outside world, ergo `io`.
21//! In other context, such interfaces are referred to as "**host functions**".
22//!
23//! Each set of host functions are defined with an instance of the
24//! [`sp_runtime_interface::runtime_interface`] macro.
25//!
26//! Most notably, this crate contains host functions for:
27//!
28//! - [`hashing`]
29//! - [`crypto`]
30//! - [`trie`]
31//! - [`offchain`]
32//! - [`storage`]
33//! - [`allocator`]
34//! - [`logging`]
35//!
36//! All of the default host functions provided by this crate, and by default contained in all
37//! substrate-based clients are amalgamated in [`SubstrateHostFunctions`].
38//!
39//! ## Externalities
40//!
41//! Host functions go hand in hand with the concept of externalities. Externalities are an
42//! environment in which host functions are provided, and thus can be accessed. Some host functions
43//! are only accessible in an externality environment that provides it.
44//!
45//! A typical error for substrate developers is the following:
46//!
47//! ```should_panic
48//! use sp_io::storage::get;
49//! # fn main() {
50//! let data = get(b"hello world");
51//! # }
52//! ```
53//!
54//! This code will panic with the following error:
55//!
56//! ```no_compile
57//! thread 'main' panicked at '`get_version_1` called outside of an Externalities-provided environment.'
58//! ```
59//!
60//! Such error messages should always be interpreted as "code accessing host functions accessed
61//! outside of externalities".
62//!
63//! An externality is any type that implements [`sp_externalities::Externalities`]. A simple example
64//! of which is [`TestExternalities`], which is commonly used in tests and is exported from this
65//! crate.
66//!
67//! ```
68//! use sp_io::{storage::get, TestExternalities};
69//! # fn main() {
70//! TestExternalities::default().execute_with(|| {
71//! let data = get(b"hello world");
72//! });
73//! # }
74//! ```
75
76#![warn(missing_docs)]
77#![cfg_attr(not(feature = "std"), no_std)]
78#![cfg_attr(enable_alloc_error_handler, feature(alloc_error_handler))]
79
80extern crate alloc;
81
82#[cfg(all(not(feature = "disable_allocator"), substrate_runtime))]
83mod global_alloc;
84
85/// Host functions for the relay chain runtime.
86pub mod relay_chain;
87pub use relay_chain::*;