Module ic_stable_structures::log

source ·
Expand description

An append-only list data structure, also known as log.

It supports arbitrary-sized entries and dynamic sizing to arbitrary number of entries (as long as the underlying memory offers enough space). This requires two independently growable Memory trait objects. For canister development it is recommended to use a crate::memory_manager.

V1 layout

This log uses two crate::Memory trait objects:

  • index memory to store the memory addresses of each entry
  • data memory to store the entries themselves

Index memory

---------------------------------------- <- Address 0
Magic "GLI"             ↕ 3 bytes
----------------------------------------
Layout version          ↕ 1 byte
----------------------------------------
Reserved space          ↕ 28 bytes
---------------------------------------- <- Address 32 (HEADER_OFFSET)
Number of entries = L   ↕ 8 bytes
---------------------------------------- <- Address 40
E_0                     ↕ 8 bytes
----------------------------------------
E_0 + E_1               ↕ 8 bytes
----------------------------------------
...
----------------------------------------
E_0 + ... + E_(L-1)     ↕ 8 bytes
----------------------------------------
Unused index entries    ↕ 8×(N-L) bytes
----------------------------------------
Unallocated space

Data memory

---------------------------------------- <- Address 0
Magic "GLD"             ↕ 3 bytes
----------------------------------------
Layout version          ↕ 1 byte
----------------------------------------
Reserved space          ↕ 28 bytes
---------------------------------------- <- Address 32 (HEADER_OFFSET)
Entry 0 bytes           ↕ E_0 bytes
----------------------------------------
Entry 1 bytes           ↕ E_1 bytes
----------------------------------------
...
----------------------------------------
Entry (L-1) bytes       ↕ E_(L-1) bytes
----------------------------------------
Unallocated space

Structs

Iter
Log
Append-only list of variable-size entries stored in stable memory.
NoSuchEntry

Enums

InitError
WriteError

Constants

DATA_MAGIC
The magic number: Growable Log Data.
INDEX_MAGIC
The magic number: Growable Log Index.