From da68b9264432eb60c3bac713638ae10701139054 Mon Sep 17 00:00:00 2001 From: Maksym Arutyunyan Date: Fri, 15 Aug 2025 10:37:07 +0200 Subject: [PATCH 1/8] docs: add contributor guide, document memory limitations, and mark deprecated APIs for cleanup --- AGENTS.md | 59 +++++++++++++++++++++++++++++++++++++++++++ src/btreemap.rs | 5 ++++ src/memory_manager.rs | 7 +++++ 3 files changed, 71 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..8fe488ad --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,59 @@ +# AGENTS.md + +## Overview + +This repository provides stable data structures for the Internet Computer that persist across canister upgrades without requiring `pre_upgrade`/`post_upgrade` hooks. The main modules include `BTreeMap` and `BTreeSet` for key-value storage and sets, `Vec` for growable arrays, `Cell` for single values, `Log` for append-only data, `MinHeap` for priority queues, and a `MemoryManager` for coordinating multiple structures in stable memory. + +## Index + +Key entry points for understanding and using this library: + +- `README.md` — quick start and basic usage patterns +- `docs/` — mdBook with concepts, design principles, and tutorials +- `src/lib.rs` — crate-level documentation and public API overview +- `examples/` — production-ready examples showing real-world usage +- `src/btreemap.rs`, `src/btreeset.rs`, `src/vec.rs`, etc. — individual module documentation +- `Cargo.toml` — version and dependency information + +## Source of truth + +Code defines behavior. Documentation must accurately reflect the current implementation. When making changes: + +- update documentation in the same PR as code changes +- ensure examples compile and run correctly +- keep API documentation synchronized with function signatures +- update book chapters when changing core concepts + +## Reading path + +Follow this sequence to understand the library: + +1. `README.md` for overview and quick examples +2. `docs/src/introduction/` for concepts and design principles +3. `docs/src/concepts/` for `Memory` trait and `MemoryManager` details +4. module documentation (`src/*.rs`) for specific data structure APIs +5. `examples/` for production usage patterns +6. code comments for implementation details + +## Checklist + +When changing public APIs: + +- describe scope of changes in PR description +- update module-level documentation for affected types +- add or update runnable examples demonstrating the change +- update book chapters if concepts change +- verify `cargo doc` builds without warnings +- verify `mdbook build` succeeds +- test examples compile and run + +## Quality bar + +Every public type and module must have: + +- short overview explaining purpose and use cases +- basic usage example that compiles +- links to related documentation or examples +- clear parameter and return value descriptions +- complexity information where relevant +- error conditions and panics documented diff --git a/src/btreemap.rs b/src/btreemap.rs index 19ad8780..c6f4ae92 100644 --- a/src/btreemap.rs +++ b/src/btreemap.rs @@ -699,12 +699,16 @@ where /// Removes all elements from the map. #[deprecated(since = "0.6.3", note = "please use `clear_new` instead")] + // TODO: In next major release (v1.0), remove this deprecated method and rename + // `clear_new` to `clear` for consistency with standard Rust collections. pub fn clear(self) -> Self { let mem = self.allocator.into_memory(); Self::new(mem) } /// Removes all elements from the map. + // TODO: In next major release (v1.0), rename this method to `clear` to follow + // standard Rust collection naming conventions. pub fn clear_new(&mut self) { self.root_addr = NULL; self.length = 0; @@ -1212,6 +1216,7 @@ where /// The new name, `iter_from_prev_key`, better reflects this behavior and /// improves code clarity. #[deprecated(note = "use `iter_from_prev_key` instead")] + // TODO: In next major release (v1.0), remove this deprecated method to clean up the API. pub fn iter_upper_bound(&self, bound: &K) -> Iter<'_, K, V, M> { self.iter_from_prev_key(bound) } diff --git a/src/memory_manager.rs b/src/memory_manager.rs index 07a2ecbf..aa06b17d 100644 --- a/src/memory_manager.rs +++ b/src/memory_manager.rs @@ -126,6 +126,13 @@ const HEADER_RESERVED_BYTES: usize = 32; /// -------------------------------------------------- <- Page ((MAX_NUM_BUCKETS - 1) * N + 1) /// Bucket MAX_NUM_BUCKETS ↕ N pages /// ``` +/// +/// # Current Limitations and Future Improvements +/// +/// - Buckets are never deallocated once assigned to a memory ID, even when the memory becomes empty +/// - Clearing data structures (BTreeMap, Vec) does not reclaim underlying bucket allocations +/// - Long-running canisters may accumulate unused buckets, increasing storage costs +/// - Future versions may include automatic bucket reclamation and memory compaction features pub struct MemoryManager { inner: Rc>>, } From 2a98e4a3a6cafb7d4773babb711e4df8f0284313 Mon Sep 17 00:00:00 2001 From: Maksym Arutyunyan <103510076+maksymar@users.noreply.github.com> Date: Fri, 15 Aug 2025 10:39:19 +0200 Subject: [PATCH 2/8] Update AGENTS.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 8fe488ad..922e39f9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,7 +2,7 @@ ## Overview -This repository provides stable data structures for the Internet Computer that persist across canister upgrades without requiring `pre_upgrade`/`post_upgrade` hooks. The main modules include `BTreeMap` and `BTreeSet` for key-value storage and sets, `Vec` for growable arrays, `Cell` for single values, `Log` for append-only data, `MinHeap` for priority queues, and a `MemoryManager` for coordinating multiple structures in stable memory. +This repository provides stable data structures for the Internet Computer that persist across canister upgrades. These structures do not require `pre_upgrade` or `post_upgrade` hooks. The main modules include `BTreeMap` and `BTreeSet` for key-value storage and sets, `Vec` for growable arrays, `Cell` for single values, `Log` for append-only data, `MinHeap` for priority queues, and a `MemoryManager` for coordinating multiple structures in stable memory. ## Index From e6a10bb64bf386b5e1214d2ee4d73e98152ad6d0 Mon Sep 17 00:00:00 2001 From: Maksym Arutyunyan <103510076+maksymar@users.noreply.github.com> Date: Fri, 15 Aug 2025 10:41:07 +0200 Subject: [PATCH 3/8] Update src/btreemap.rs Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- src/btreemap.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/btreemap.rs b/src/btreemap.rs index c6f4ae92..018ce367 100644 --- a/src/btreemap.rs +++ b/src/btreemap.rs @@ -700,7 +700,7 @@ where /// Removes all elements from the map. #[deprecated(since = "0.6.3", note = "please use `clear_new` instead")] // TODO: In next major release (v1.0), remove this deprecated method and rename - // `clear_new` to `clear` for consistency with standard Rust collections. + // TODO: In next major release (v1.0), remove this deprecated method and rename `clear_new` to `clear` for consistency with standard Rust collections. pub fn clear(self) -> Self { let mem = self.allocator.into_memory(); Self::new(mem) From 8796dc5e58ca3c60e80ec5ebd171e0d5bc8bc41a Mon Sep 17 00:00:00 2001 From: Maksym Arutyunyan <103510076+maksymar@users.noreply.github.com> Date: Fri, 15 Aug 2025 10:41:26 +0200 Subject: [PATCH 4/8] Update AGENTS.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- AGENTS.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 922e39f9..bd99f85e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -3,7 +3,17 @@ ## Overview This repository provides stable data structures for the Internet Computer that persist across canister upgrades. These structures do not require `pre_upgrade` or `post_upgrade` hooks. The main modules include `BTreeMap` and `BTreeSet` for key-value storage and sets, `Vec` for growable arrays, `Cell` for single values, `Log` for append-only data, `MinHeap` for priority queues, and a `MemoryManager` for coordinating multiple structures in stable memory. +This repository provides stable data structures for the Internet Computer that persist across canister upgrades. These structures do not require `pre_upgrade` or `post_upgrade` hooks. +The main modules include: + +- `BTreeMap` — key-value storage +- `BTreeSet` — sets +- `Vec` — growable arrays +- `Cell` — single values +- `Log` — append-only data +- `MinHeap` — priority queues +- `MemoryManager` — coordinates multiple structures in stable memory ## Index Key entry points for understanding and using this library: From fa7d058cefc0daef64c5a3c319a13cea652f9e2c Mon Sep 17 00:00:00 2001 From: Maksym Arutyunyan Date: Fri, 15 Aug 2025 10:42:41 +0200 Subject: [PATCH 5/8] . --- AGENTS.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index bd99f85e..68d8a20a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,7 +2,6 @@ ## Overview -This repository provides stable data structures for the Internet Computer that persist across canister upgrades. These structures do not require `pre_upgrade` or `post_upgrade` hooks. The main modules include `BTreeMap` and `BTreeSet` for key-value storage and sets, `Vec` for growable arrays, `Cell` for single values, `Log` for append-only data, `MinHeap` for priority queues, and a `MemoryManager` for coordinating multiple structures in stable memory. This repository provides stable data structures for the Internet Computer that persist across canister upgrades. These structures do not require `pre_upgrade` or `post_upgrade` hooks. The main modules include: @@ -14,6 +13,7 @@ The main modules include: - `Log` — append-only data - `MinHeap` — priority queues - `MemoryManager` — coordinates multiple structures in stable memory + ## Index Key entry points for understanding and using this library: @@ -39,11 +39,11 @@ Code defines behavior. Documentation must accurately reflect the current impleme Follow this sequence to understand the library: 1. `README.md` for overview and quick examples -2. `docs/src/introduction/` for concepts and design principles -3. `docs/src/concepts/` for `Memory` trait and `MemoryManager` details -4. module documentation (`src/*.rs`) for specific data structure APIs -5. `examples/` for production usage patterns -6. code comments for implementation details +1. `docs/src/introduction/` for concepts and design principles +1. `docs/src/concepts/` for `Memory` trait and `MemoryManager` details +1. module documentation (`src/*.rs`) for specific data structure APIs +1. `examples/` for production usage patterns +1. code comments for implementation details ## Checklist From 9fa4380a26c341797dc01e527fd20538712a43e5 Mon Sep 17 00:00:00 2001 From: Maksym Arutyunyan Date: Fri, 15 Aug 2025 10:43:54 +0200 Subject: [PATCH 6/8] . --- src/btreemap.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/btreemap.rs b/src/btreemap.rs index 018ce367..c6f4ae92 100644 --- a/src/btreemap.rs +++ b/src/btreemap.rs @@ -700,7 +700,7 @@ where /// Removes all elements from the map. #[deprecated(since = "0.6.3", note = "please use `clear_new` instead")] // TODO: In next major release (v1.0), remove this deprecated method and rename - // TODO: In next major release (v1.0), remove this deprecated method and rename `clear_new` to `clear` for consistency with standard Rust collections. + // `clear_new` to `clear` for consistency with standard Rust collections. pub fn clear(self) -> Self { let mem = self.allocator.into_memory(); Self::new(mem) From 3d98a32d4c446292ca0017097b37879c3b9e1656 Mon Sep 17 00:00:00 2001 From: Maksym Arutyunyan <103510076+maksymar@users.noreply.github.com> Date: Fri, 15 Aug 2025 10:45:41 +0200 Subject: [PATCH 7/8] Update src/memory_manager.rs Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- src/memory_manager.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/memory_manager.rs b/src/memory_manager.rs index aa06b17d..463e4e0a 100644 --- a/src/memory_manager.rs +++ b/src/memory_manager.rs @@ -132,7 +132,7 @@ const HEADER_RESERVED_BYTES: usize = 32; /// - Buckets are never deallocated once assigned to a memory ID, even when the memory becomes empty /// - Clearing data structures (BTreeMap, Vec) does not reclaim underlying bucket allocations /// - Long-running canisters may accumulate unused buckets, increasing storage costs -/// - Future versions may include automatic bucket reclamation and memory compaction features +/// - Future versions may consider automatic bucket reclamation and memory compaction features pub struct MemoryManager { inner: Rc>>, } From c29f537f3677660c6249999b2515387589c5cd3e Mon Sep 17 00:00:00 2001 From: Maksym Arutyunyan Date: Fri, 15 Aug 2025 11:06:05 +0200 Subject: [PATCH 8/8] chore: use AGENTS title --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 68d8a20a..04c4aa72 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,4 +1,4 @@ -# AGENTS.md +# AGENTS ## Overview