{"id":36983035,"url":"https://github.com/consistent-milk12/masstree","last_synced_at":"2026-01-13T22:54:58.421Z","repository":{"id":328670497,"uuid":"1116232859","full_name":"consistent-milk12/masstree","owner":"consistent-milk12","description":"An implementation of the C++ Masstree data structure in Rust.","archived":false,"fork":false,"pushed_at":"2026-01-13T17:02:31.000Z","size":4006,"stargazers_count":9,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-13T22:54:51.400Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/consistent-milk12.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-14T13:18:07.000Z","updated_at":"2026-01-13T18:08:28.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/consistent-milk12/masstree","commit_stats":null,"previous_names":["consistent-milk12/madtree"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/consistent-milk12/masstree","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/consistent-milk12%2Fmasstree","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/consistent-milk12%2Fmasstree/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/consistent-milk12%2Fmasstree/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/consistent-milk12%2Fmasstree/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/consistent-milk12","download_url":"https://codeload.github.com/consistent-milk12/masstree/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/consistent-milk12%2Fmasstree/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28405138,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T21:51:37.118Z","status":"ssl_error","status_checked_at":"2026-01-13T21:45:14.585Z","response_time":56,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-13T22:54:58.336Z","updated_at":"2026-01-13T22:54:58.411Z","avatar_url":"https://github.com/consistent-milk12.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"# masstree\n\nA high-performance concurrent ordered map for Rust. It stores keys as `\u0026[u8]` and supports variable-length keys by building a trie of B+trees, based on the [Masstree paper](https://pdos.csail.mit.edu/papers/masstree:eurosys12.pdf)\n\n**Disclaimer:** This is an independent implementation. It is not endorsed by, affiliated with, or connected to the original Masstree authors or their institutions.\n\n## Features\n\n- Ordered map for byte keys (lexicographic ordering)\n- Lock-free reads with version validation\n- Concurrent inserts and deletes with fine-grained leaf locking\n- Zero-copy range scans with `scan_ref` and `scan_prefix`\n- Memory reclamation via hyaline scheme (`seize` crate)\n- Lazy leaf coalescing for deleted entries\n- Two node widths: `MassTree` (WIDTH=24) and `MassTree15` (WIDTH=15)\n\n## Status\n\n**v0.5.0** — Core feature complete. Heavily tested but concurrent data structures require extensive stress testing beyond what tests (even though still quite comprehensive) provide. The unsafe code passes Miri with strict-provenance flag. It should be noted that the C++ implementation is a research project, not a library specifically developed for production usage. So it is quite possible that there are still various rare edge cases and soundness issues that still haven't been addressed.\n\n| Feature | Status |\n|---------|--------|\n| `get`, `get_ref` | Lock-free with version validation |\n| `insert` | Fine-grained leaf locking |\n| `remove` | Concurrent deletion with memory reclamation |\n| `scan`, `scan_ref`, `scan_prefix` | Zero-copy range iteration |\n| `DoubleEndedIterator` | Reverse iteration support |\n| Leaf coalescing | Lazy queue-based cleanup |\n| Memory reclamation | Hyaline scheme via `seize` crate |\n\n**Tests:** 939 tests (unit + 88 ported from C++ reference + proptests + stress tests). Miri strict provenance clean.\n\n**Not yet implemented:** `Entry` API, `Extend`/`FromIterator`.\n\n## Install\n\n```toml\n[dependencies]\nmasstree = { version = \"0.5.0\", features = [\"mimalloc\"] }\n```\n\nMSRV is Rust 1.92+ (Edition 2024).\n\nThe `mimalloc` feature sets the global allocator. If your project already uses a custom allocator, omit this feature.\n\n## Quick Start\n\n```rust\nuse masstree::MassTree;\n\nlet tree: MassTree\u003cu64\u003e = MassTree::new();\nlet guard = tree.guard();\n\n// Insert\ntree.insert_with_guard(b\"hello\", 123, \u0026guard).unwrap();\ntree.insert_with_guard(b\"world\", 456, \u0026guard).unwrap();\n\n// Point lookup\nassert_eq!(tree.get_ref(b\"hello\", \u0026guard), Some(\u0026123));\n\n// Remove\ntree.remove_with_guard(b\"hello\", \u0026guard).unwrap();\nassert_eq!(tree.get_ref(b\"hello\", \u0026guard), None);\n\n// Range scan (zero-copy)\ntree.scan_ref(b\"a\"..b\"z\", |key, value| {\n    println!(\"{:?} -\u003e {}\", key, value);\n    true // continue scanning\n}, \u0026guard);\n\n// Prefix scan\ntree.scan_prefix(b\"wor\", |key, value| {\n    println!(\"{:?} -\u003e {}\", key, value);\n    true\n}, \u0026guard);\n```\n\n## Ergonomic APIs\n\nFor simpler use cases, auto-guard versions create guards internally:\n\n```rust\nuse masstree::MassTree;\n\nlet tree: MassTree\u003cu64\u003e = MassTree::new();\n\n// Auto-guard versions (simpler but slightly more overhead per call)\ntree.insert(b\"key1\", 100).unwrap();\ntree.insert(b\"key2\", 200).unwrap();\n\nassert_eq!(tree.get(b\"key1\"), Some(std::sync::Arc::new(100)));\nassert_eq!(tree.len(), 2);\nassert!(!tree.is_empty());\n\ntree.remove(b\"key1\").unwrap();\n```\n\n### Range Iteration\n\n```rust\nuse masstree::{MassTree, RangeBound};\n\nlet tree: MassTree\u003cu64\u003e = MassTree::new();\nlet guard = tree.guard();\n\n// Populate\nfor i in 0..100u64 {\n    tree.insert_with_guard(\u0026i.to_be_bytes(), i, \u0026guard).unwrap();\n}\n\n// Iterator-based range scan\nfor entry in tree.range(RangeBound::Included(b\"\"), RangeBound::Unbounded, \u0026guard) {\n    println!(\"{:?} -\u003e {:?}\", entry.key(), entry.value());\n}\n\n// Full iteration\nfor entry in tree.iter(\u0026guard) {\n    println!(\"{:?}\", entry.key());\n}\n```\n\n## When to Use\n\n**May work well for:**\n\n- Long keys with shared prefixes (URLs, file paths, UUIDs)\n- Range scans over ordered data\n- Mixed read/write workloads\n- High-contention scenarios (the trie structure helps here)\n\n**Consider alternatives for:**\n\n- Unordered point lookups → `dashmap`\n- Pure insert-only workloads → `scc::TreeIndex`\n- Integer keys only → `congee` (ART-based)\n- Read-heavy with rare writes → `RwLock\u003cBTreeMap\u003e`\n\n## Variant Selection\n\nTwo variants are provided with different performance characteristics:\n\n| Variant | Best For |\n|---------|----------|\n| `MassTree15` | Range scans, writes, shared-prefix keys, contention |\n| `MassTree` (WIDTH=24) | Random-access reads, single-threaded point ops |\n\n`MassTree15` tends to perform better in our benchmarks due to cheaper u64 atomics and better cache utilization. Consider it for most workloads unless you have uniform random-access patterns.\n\n```rust\nuse masstree::{MassTree, MassTree15, MassTree24Inline, MassTree15Inline};\n\n// Default: WIDTH=24, Arc-based storage\nlet tree: MassTree\u003cu64\u003e = MassTree::new();\n\n// WIDTH=15, Arc-based storage (recommended for most workloads)\nlet tree15: MassTree15\u003cu64\u003e = MassTree15::new();\n\n// Inline storage for Copy types (no Arc overhead)\nlet inline: MassTree24Inline\u003cu64\u003e = MassTree24Inline::new();\nlet inline15: MassTree15Inline\u003cu64\u003e = MassTree15Inline::new();\n```\n\n## How It Works\n\nMasstree splits keys into 8-byte chunks, creating a trie where each node is a B+tree:\n\n```text\nKey: \"users/alice/profile\" (19 bytes)\n     └─ Layer 0: \"users/al\" (8 bytes)\n        └─ Layer 1: \"ice/prof\" (8 bytes)\n           └─ Layer 2: \"ile\" (3 bytes)\n```\n\nKeys with shared prefixes share upper layers, making lookups efficient for hierarchical data.\n\n## Examples\n\nThe `examples/` directory contains comprehensive usage examples:\n\n```bash\ncargo run --example basic_usage --release      # Core API walkthrough\ncargo run --example rayon_parallel --release   # Parallel processing with Rayon\ncargo run --example tokio_async --release      # Async integration with Tokio\ncargo run --example url_cache --release        # Real-world URL cache\ncargo run --example session_store --release    # Concurrent session store\n```\n\n### Rayon Integration\n\nMassTree works seamlessly with Rayon for parallel bulk operations:\n\n```rust\nuse masstree::MassTree15Inline;\nuse rayon::prelude::*;\nuse std::sync::Arc;\n\nlet tree: Arc\u003cMassTree15Inline\u003cu64\u003e\u003e = Arc::new(MassTree15Inline::new());\n\n// Parallel bulk insert (~10M ops/sec)\n(0..1_000_000).into_par_iter().for_each(|i| {\n    let key = format!(\"key/{i:08}\");\n    let guard = tree.guard();\n    let _ = tree.insert_with_guard(key.as_bytes(), i, \u0026guard);\n});\n\n// Parallel lookups (~45M ops/sec)\nlet sum: u64 = (0..1_000_000).into_par_iter()\n    .map(|i| {\n        let key = format!(\"key/{i:08}\");\n        let guard = tree.guard();\n        tree.get_with_guard(key.as_bytes(), \u0026guard).unwrap_or(0)\n    })\n    .sum();\n```\n\n### Tokio Integration\n\nMassTree is thread-safe but guards cannot be held across `.await` points:\n\n```rust\nuse masstree::MassTree15;\nuse std::sync::Arc;\n\nlet tree: Arc\u003cMassTree15\u003cString\u003e\u003e = Arc::new(MassTree15::new());\n\n// Spawn async tasks that share the tree\nlet handle = tokio::spawn({\n    let tree = Arc::clone(\u0026tree);\n    async move {\n        // Guard must be scoped - cannot be held across await!\n        {\n            let guard = tree.guard();\n            let _ = tree.insert_with_guard(b\"key\", \"value\".to_string(), \u0026guard);\n        } // guard dropped here\n\n        tokio::time::sleep(Duration::from_millis(10)).await;\n\n        // Create new guard after await\n        let guard = tree.guard();\n        tree.get_with_guard(b\"key\", \u0026guard)\n    }\n});\n\n// For CPU-intensive operations, use spawn_blocking\nlet tree_clone = Arc::clone(\u0026tree);\ntokio::task::spawn_blocking(move || {\n    let guard = tree_clone.guard();\n    for entry in tree_clone.iter(\u0026guard) {\n        // Process entries...\n    }\n}).await;\n```\n\n## Crate Features\n\n- `mimalloc` — Use mimalloc as global allocator (recommended)\n- `tracing` — Enable structured logging to `logs/masstree.jsonl`\n\n## License\n\nMIT. See `LICENSE`.\n\n## References\n\n- [Masstree Paper (EuroSys 2012)](https://pdos.csail.mit.edu/papers/masstree:eurosys12.pdf)\n- [C++ Reference Implementation](https://github.com/kohler/masstree-beta)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fconsistent-milk12%2Fmasstree","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fconsistent-milk12%2Fmasstree","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fconsistent-milk12%2Fmasstree/lists"}