ExperimentalStableMemory
Byte-level access to (virtual) stable memory.
WARNING: As its name suggests, this library is experimental, subject to change and may be replaced by safer alternatives in later versions of Motoko. Use at your own risk and discretion.
This is a lightweight abstraction over IC stable memory and supports persisting raw binary data across Motoko upgrades. Use of this module is fully compatible with Motoko’s use of stable variables, whose persistence mechanism also uses (real) IC stable memory internally, but does not interfere with this API.
Memory is allocated, using 'grow(pages), sequentially and on demand, in units of 64KiB pages, starting with 0 allocated pages.
New pages are zero initialized.
Growth is capped by a soft limit on page count controlled by compile-time flag
`--max-stable-pages <n>
(the default is 65536, or 4GiB).
Each load
operation loads from byte address offset
in little-endian
format using the natural bit-width of the type in question.
The operation traps if attempting to read beyond the current stable memory size.
Each store
operation stores to byte address offset
in little-endian format using the natural bit-width of the type in question.
The operation traps if attempting to write beyond the current stable memory size.
Text values can be handled by using Text.decodeUtf8
and Text.encodeUtf8
, in conjunction with loadBlob
and storeBlob
.
The current page allocation and page contents is preserved across upgrades.
NB: The IC’s actual stable memory size (ic0.stable_size
) may exceed the
page size reported by Motoko function size()
.
This (and the cap on growth) are to accommodate Motoko’s stable variables.
Applications that plan to use Motoko stable variables sparingly or not at all can
increase --max-stable-pages
as desired, approaching the IC maximum (currently 8GiB).
All applications should reserve at least one page for stable variable data, even when no stable variables are used.
size
let size : () -> (pages : Nat64)
Current size of the stable memory, in pages.
Each page is 64KiB (65536 bytes).
Initially 0
.
Preserved across upgrades, together with contents of allocated
stable memory.
grow
let grow : (new_pages : Nat64) -> (oldpages : Nat64)
Grow current size
of stable memory by pagecount
pages.
Each page is 64KiB (65536 bytes).
Returns previous size
when able to grow.
Returns 0xFFFF_FFFF_FFFF_FFFF
if remaining pages insufficient.
Every new page is zero-initialized, containing byte 0 at every offset.
Function grow
is capped by a soft limit on size
controlled by compile-time flag
--max-stable-pages <n>
(the default is 65536, or 4GiB).