subsoil 0.2.0

Soil primitives foundation crate
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60

// This file is part of Soil.

// Copyright (C) Soil contributors.
// Copyright (C) Parity Technologies (UK) Ltd.
// SPDX-License-Identifier: Apache-2.0 OR GPL-3.0-or-later WITH Classpath-exception-2.0

//! Collection of allocator implementations.
//!
//! This module provides the following allocator implementations:
//! - A freeing-bump allocator: [`FreeingBumpHeapAllocator`]

#[cfg(feature = "std")]
mod error;
#[cfg(feature = "std")]
mod freeing_bump;

#[cfg(feature = "std")]
pub use error::Error;
#[cfg(feature = "std")]
pub use freeing_bump::{AllocationStats, FreeingBumpHeapAllocator};

/// The size of one wasm page in bytes.
///
/// The wasm memory is divided into pages, meaning the minimum size of a memory is one page.
#[cfg(feature = "std")]
const PAGE_SIZE: u32 = 65536;

/// The maximum number of wasm pages that can be allocated.
///
/// 4GiB / [`PAGE_SIZE`].
#[cfg(feature = "std")]
const MAX_WASM_PAGES: u32 = (4u64 * 1024 * 1024 * 1024 / PAGE_SIZE as u64) as u32;

/// Grants access to the memory for the allocator.
///
/// Memory of wasm is allocated in pages. A page has a constant size of 64KiB. The maximum allowed
/// memory size as defined in the wasm specification is 4GiB (65536 pages).
#[cfg(feature = "std")]
pub trait Memory {
	/// Run the given closure `run` and grant it write access to the raw memory.
	#[cfg(feature = "std")]
	fn with_access_mut<R>(&mut self, run: impl FnOnce(&mut [u8]) -> R) -> R;
	/// Run the given closure `run` and grant it read access to the raw memory.
	#[cfg(feature = "std")]
	fn with_access<R>(&self, run: impl FnOnce(&[u8]) -> R) -> R;
	/// Grow the memory by `additional` pages.
	#[cfg(feature = "std")]
	fn grow(&mut self, additional: u32) -> Result<(), ()>;
	/// Returns the current number of pages this memory has allocated.
	#[cfg(feature = "std")]
	fn pages(&self) -> u32;
	/// Returns the maximum number of pages this memory is allowed to allocate.
	///
	/// The returned number needs to be smaller or equal to `65536`. The returned number needs to be
	/// bigger or equal to [`Self::pages`].
	///
	/// If `None` is returned, there is no maximum (besides the maximum defined in the wasm spec).
	#[cfg(feature = "std")]
	fn max_pages(&self) -> Option<u32>;
}