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 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;

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.