Struct BTreeMapRegion 

pub struct BTreeMapRegion<K: Storable + Ord + Clone, V: Storable, M: Memory = DefaultMemoryImpl> { /* private fields */ }

A B-tree view inside one existing, governed allocation lease.

The caller retains its Rc<RuntimeMemory> for disjoint application frames. Each collection operation loads the current upstream root and allocator; multiple views may interleave operations without retaining stale roots. Key scans return owned snapshots, so no cached tree or iterator escapes. Applications own namespace bounds, codec admission and recovery policy.

Construction performs no IO. Inspect retained framing with Self::read before calling collection operations, which retain upstream load/panic contracts. Only Self::initialize creates a tree, and only in an empty region. No method reinitializes nonempty memory or exports raw backing. As with ordinary collections, callers must not reenter collection access from a codec or mutate the tree’s bytes through their retained lease.

Implementations

impl<K: Storable + Ord + Clone, V: Storable, M: Memory> BTreeMapRegion<K, V, M>

pub fn new(memory: Rc<RuntimeMemory<M>>, pages: Range<u64>) -> Self

Select an absolute, half-open range of 65,536-byte allocation pages.

Retains the same allocation lease; no allocation or collection is opened. Other owners of the Rc may access disjoint frames in that allocation. Drop every view and the caller’s last Rc before reopening the lease.

Panics

Panics unless pages.start < pages.end <= 4_194_304.

pub fn allocated_pages(&self) -> u64

Return the currently allocated relative extent in Wasm pages.

pub fn read(&self, offset: u64, dst: &mut [u8])

Read relative bytes for the application’s retained-framing admission.

Panics

Panics before IO if the complete read exceeds the allocated region. An empty read is valid at the region’s end, but not beyond it.

pub fn initialize(&mut self)

Create an upstream tree only when the selected region has zero pages.

Call before reserving extra pages. Retained trees need no initialization: admit their framing and use the operations directly.

Panics

Panics without writing if the region is nonempty. Empty-region creation retains upstream growth and panic contracts.

pub fn reserve_pages(&mut self, minimum: u64) -> Result<(), RegionGrowError>

Reserve an absolute relative extent without promising entry capacity.

Errors

Returns a region-limit or IC Memory growth error without changing bytes or allocation accounting. A satisfied request performs no growth or IO. Callers own byte/page budgets and must qualify them for their codecs. Mutations retain upstream failure semantics; this is not a transaction around an insert that later runs out of space or panics in a codec.

pub fn get(&self, key: &K) -> Option<V>

Read a record using the current retained root.

pub fn insert(&mut self, key: K, value: V) -> Option<V>

Insert using the current retained root and upstream mutation semantics.

pub fn remove(&mut self, key: &K) -> Option<V>

Remove using the current retained root and upstream mutation semantics.

pub fn len(&self) -> u64

Return the current tree’s record count across all namespaces.

pub fn is_empty(&self) -> bool

Return whether the current tree has no records.

pub fn keys_range(&self, bounds: impl RangeBounds<K>) -> IntoIter<K>

Snapshot ordered keys within the caller’s namespace/range bounds.

The scan completes before returning; the iterator retains owned keys, with no collection cache, memory handle or borrow across later mutations.

pub fn keys_range_limited( &self, bounds: impl RangeBounds<K>, limit: usize, ) -> IntoIter<K>

Snapshot at most limit ordered keys, stopping iteration at that bound.

Unlike keys_range(bounds).take(limit), this bounds collection work before allocating the snapshot. Zero returns without loading the tree. Resume with an excluded last key; intervening mutations are visible to each call. The limit bounds key count, not encoded bytes or instruction cost.