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.
- Stable data structures release their memory automatically, following Rust’s ownership rules.
- Stable data structures also obey and enforce Rust’s borrowing and lifetime rules.
- 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.
- Each data structure’s performance is reasonably close to its std’s analog.
- Supported stable data structures: box, vec, log, hash-map, hash-set, btree-map, btree-set, certified-map.
- 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.
pub use ic_stable_memory_derive as derive;
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;
- All collections provided by this crate
- Traits and algorithms for internal data encoding Traits and encoding algorithms used by this crate.
- Stable memory allocator and related structs Various functions and data structures to organize and work with raw stable memory.
- Stable memory smart-pointers Smart-pointers and StableType trait
- Various utilities: certification, stable memory API wrapper etc. Various utilities used by this crate
- Trait that is used to hash a leaf value of a [HashTree].
- Trait that is used to serialize labels of a [HashTree] into bytes.
- Deallocates an already allocated SSlice freeing it’s memory.
- An alias for stable_memory_pre_upgrade.
- Returns the amount of allocated stable memory in bytes.
- Returns the amount of stable memory in bytes which is under the allocator’s management.
- Returns the amount of free stable memory in bytes.
- Checks if it would be possible to allocate a block of stable memory of the provided size right now.
- Attempts to reallocate a memory block growing its size and possibly moving its content to a new location.
- An alias for stable_memory_post_upgrade.
- Retrieves a pointer to some SBox stored previously.
- Initializes the memory allocator.
- Retrieves the memory allocator from stable memory.
- Persists the memory allocator into stable memory between canister upgrades.