Crate ic_stable_roaring 

IC Stable Roaring

Persistent Roaring Bitmap for Internet Computer canisters. It stores bitmap state in stable memory so it survives upgrades without application-level serialization hooks.

How it works

Reads use a heap mirror. Logical mutations are appended to a stable-memory journal and periodically checkpointed as a Roaring snapshot. Calling init restores the snapshot and replays pending journal records.

Example

Each bitmap must exclusively own its stable memory. Use MemoryManager when a canister has multiple stable structures.

use ic_stable_roaring::StableRoaringBitmap;
use ic_stable_structures::{
    memory_manager::{MemoryId, MemoryManager},
    DefaultMemoryImpl,
};

let memory_manager = MemoryManager::init(DefaultMemoryImpl::default());
let bitmap = StableRoaringBitmap::init(memory_manager.get(MemoryId::new(0))).unwrap();

bitmap.insert(42).unwrap();
assert!(bitmap.contains(42));

Usage

• Use StableRoaringBitmap::init on first boot and after every upgrade or reload.
• insert, clear, ensure_len, and truncate return Result; contains reads the heap mirror.
• len is the exclusive logical bit length, not the number of set bits.
• Do not mutate the same Memory through another structure while a bitmap uses it.

Journal capacity

The default JOURNAL_CAP_SLOTS compile-time setting is 4096 (a 20 KiB journal). Raise it only for a write-heavy workload that can accept slower recovery of a long pending journal.

The capacity is stored in the stable header. Builds with different capacities are incompatible on the same stable-memory image; migrate into fresh storage before changing it for a live canister.

init expects valid, isolated stable memory. It validates the reachable header, snapshot, and journal prefix, then stops at the first empty journal record.

Documentation

• API reference: public API, errors, durability, and complexity.
• Stable-memory layout and recovery
• Contributing guide: development checks and layout-change rules.

Contributing

Issues and pull requests are welcome on GitHub. Please read the contributing guide and security policy first.

License

Licensed under either Apache License, Version 2.0 or MIT License, at your option.

Re-exports

pub use bitmap::RoaringBitmap as StableRoaringBitmap;

pub use bitmap::BitmapError;

pub use bitmap::ContainsView;

pub use bitmap::InitError;

pub use bitmap::RoaringBitmap;

Modules

bitmap

Roaring bitmap types backed by the Memory trait.

Structs

GrowFailed

Stable memory could not be grown to satisfy a write, checkpoint, or initialization layout.