pub struct BTreeMapRegion<K: Storable + Ord + Clone, V: Storable, M: Memory = DefaultMemoryImpl> { /* private fields */ }Expand description
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 owned tree 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 return collection admission errors. 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§
Source§impl<K: Storable + Ord + Clone, V: Storable, M: Memory> BTreeMapRegion<K, V, M>
impl<K: Storable + Ord + Clone, V: Storable, M: Memory> BTreeMapRegion<K, V, M>
Sourcepub fn new(memory: Rc<RuntimeMemory<M>>, pages: Range<u64>) -> Self
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.
Sourcepub fn allocated_pages(&self) -> u64
pub fn allocated_pages(&self) -> u64
Return the currently allocated relative extent in Wasm pages.
Sourcepub fn read(&self, offset: u64, dst: &mut [u8])
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.
Sourcepub fn initialize(&mut self) -> Result<(), CollectionError>
pub fn initialize(&mut self) -> Result<(), CollectionError>
Create an owned 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.
§Errors
Rejects a nonempty region or capacity refusal without initializing a replacement.
Sourcepub fn reserve_pages(&mut self, minimum: u64) -> Result<(), RegionGrowError>
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 Storage 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 the host failure contract; this is not a transaction around an insert that later runs out of space or panics in a codec.
Sourcepub fn get(&self, key: &K) -> Result<Option<V>, CollectionError>
pub fn get(&self, key: &K) -> Result<Option<V>, CollectionError>
Read a record using the current retained root.
§Errors
Reports structural, integrity or application decoding failures without writing.
Sourcepub fn insert(&mut self, key: K, value: V) -> Result<Option<V>, CollectionError>
pub fn insert(&mut self, key: K, value: V) -> Result<Option<V>, CollectionError>
Insert using the current retained root and staged node updates.
§Errors
Rejects encoding, decoding, structural or capacity errors before committing writes.
Sourcepub fn remove(&mut self, key: &K) -> Result<Option<V>, CollectionError>
pub fn remove(&mut self, key: &K) -> Result<Option<V>, CollectionError>
Remove using the current retained root and staged node updates.
§Errors
Rejects decoding or structural errors before committing removal.
Sourcepub fn len(&self) -> Result<u64, CollectionError>
pub fn len(&self) -> Result<u64, CollectionError>
Return the current tree’s record count across all namespaces.
§Errors
Reports invalid region metadata or incompatible codec bounds.
Sourcepub fn is_empty(&self) -> Result<bool, CollectionError>
pub fn is_empty(&self) -> Result<bool, CollectionError>
Return whether the current tree has no records.
§Errors
Reports invalid region metadata or incompatible codec bounds.
Sourcepub fn keys_range(
&self,
bounds: impl RangeBounds<K>,
) -> Result<IntoIter<K>, CollectionError>
pub fn keys_range( &self, bounds: impl RangeBounds<K>, ) -> Result<IntoIter<K>, CollectionError>
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.
§Errors
Reports invalid ranges, retained structure or key decoding failures.
Sourcepub fn keys_range_limited(
&self,
bounds: impl RangeBounds<K>,
limit: usize,
) -> Result<IntoIter<K>, CollectionError>
pub fn keys_range_limited( &self, bounds: impl RangeBounds<K>, limit: usize, ) -> Result<IntoIter<K>, CollectionError>
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.
§Errors
Reports invalid ranges, retained structure or key decoding failures.