Module ic_stable_structures::log

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
• ThreadLocalRefIterator

Enums

• InitError
• WriteError

Constants

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

Functions

• iter_thread_local
  Returns an iterator over entries in the log stored in a thread-local variable.