Crate ic_stable_memory

This crate provides a number of “stable” data structures - collections that use canister’s stable memory for storage, as well as other primitives that allow storing all data of your canister in stable memory. This crate also provides the SCertifiedBTreeMap - a Merkle-tree based collection that can be used to include custom data into canister’s certified state tree.

This documentation only covers API and some implementation details. For more useful info and tutorials, please visit project’s Github page.

Features

1. Stable data structures release their memory automatically, following Rust’s ownership rules.
2. Stable data structures also obey and enforce Rust’s borrowing and lifetime rules.
3. Each data structure is aware of the limited nature of memory in IC and allows programmatic reaction for situations when your canister is out of stable memory.
4. Each data structure’s performance is reasonably close to its std’s analog.
5. Supported stable data structures: box, vec, log, hash-map, hash-set, btree-map, btree-set, certified-map.
6. In addition to these data structures, this crate provides you with a fully featured toolset to build your own data structure, if you need something more domain-specific.

Re-exports

pub use crate::utils::mem_context::stable;

pub use crate::utils::mem_context::OutOfMemory;

pub use crate::utils::mem_context::PAGE_SIZE_BYTES;

pub use encoding::AsDynSizeBytes;

pub use encoding::AsFixedSizeBytes;

pub use encoding::Buffer;

pub use primitive::s_box::SBox;

pub use primitive::StableType;

pub use ic_stable_memory_derive as derive;

Modules

collections

All collections provided by this crate

encoding

Traits and algorithms for internal data encoding Traits and encoding algorithms used by this crate.

mem

Stable memory allocator and related structs Various functions and data structures to organize and work with raw stable memory.

primitive

Stable memory smart-pointers Smart-pointers and StableType trait

utils

Various utilities: certification, stable memory API wrapper etc. Various utilities used by this crate

Macros

measure

Traits

AsHashTree

Trait that is used to hash a leaf value of a [HashTree].

AsHashableBytes

Trait that is used to serialize labels of a [HashTree] into bytes.

Functions

_debug_print_allocator

_debug_validate_allocator

allocate^⚠

Attempts to allocate a new SSlice of at least the required size or returns an OutOfMemory error if there is no continuous stable memory memory block of that size can be allocated.

deallocate

Deallocates an already allocated SSlice freeing it’s memory.

deinit_allocator

An alias for stable_memory_pre_upgrade.

get_allocated_size

Returns the amount of allocated stable memory in bytes.

get_available_size

Returns the amount of stable memory in bytes which is under the allocator’s management.

get_free_size

Returns the amount of free stable memory in bytes.

get_max_pages

Returns max_pages parameter.

init_allocator

An alias for stable_memory_init, but allows limiting the maximum number of stable memory pages that the allocator can grow. [init_allocator(0)] works exactly the same as stable_memory_init().

make_sure_can_allocate

Checks if it would be possible to allocate a block of stable memory of the provided size right now.

reallocate^⚠

Attempts to reallocate a memory block growing its size and possibly moving its content to a new location.

reinit_allocator

An alias for stable_memory_post_upgrade.

retrieve_custom_data

Retrieves a pointer to some SBox stored previously.

stable_memory_init

Initializes the memory allocator.

stable_memory_post_upgrade

Retrieves the memory allocator from stable memory.

stable_memory_pre_upgrade

Persists the memory allocator into stable memory between canister upgrades.

store_custom_data

Persists a pointer to an SBox between canister upgrades mapped to some unique usize key.