{"id":27416482,"url":"https://github.com/declanvk/blart","last_synced_at":"2025-04-14T09:49:15.062Z","repository":{"id":41887133,"uuid":"453329869","full_name":"declanvk/blart","owner":"declanvk","description":null,"archived":false,"fork":false,"pushed_at":"2024-11-17T19:41:37.000Z","size":3440,"stargazers_count":41,"open_issues_count":11,"forks_count":4,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-28T08:07:51.310Z","etag":null,"topics":["adaptive-radix-tree","fuzzing","rust"],"latest_commit_sha":null,"homepage":"https://declanvk.github.io/blart/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/declanvk.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE-APACHE","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}},"created_at":"2022-01-29T07:38:06.000Z","updated_at":"2025-03-21T11:39:22.000Z","dependencies_parsed_at":"2024-06-20T06:33:33.246Z","dependency_job_id":"f0ad01b1-1400-4ad2-aeb0-9b0a73ac562f","html_url":"https://github.com/declanvk/blart","commit_stats":{"total_commits":160,"total_committers":1,"mean_commits":160.0,"dds":0.0,"last_synced_commit":"6b6bf4bbd048637eea2884c0ba45f1da302b2818"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/declanvk%2Fblart","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/declanvk%2Fblart/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/declanvk%2Fblart/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/declanvk%2Fblart/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/declanvk","download_url":"https://codeload.github.com/declanvk/blart/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248859228,"owners_count":21173333,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["adaptive-radix-tree","fuzzing","rust"],"created_at":"2025-04-14T09:49:14.347Z","updated_at":"2025-04-14T09:49:15.048Z","avatar_url":"https://github.com/declanvk.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# BLART\n\n[![Crates.io][crates-badge]][crates-url]\n[![Docs.rs][docs-badge]][docs-url]\n\nBLART is an implementation of an adaptive radix tree, used as backing for map and set data structures. Adaptive radix\ntrees offer great space efficiency and performance on keys that decompose into byte strings.\n\n[crates-badge]: https://img.shields.io/crates/v/blart\n[crates-url]: https://crates.io/crates/blart\n[docs-badge]: https://img.shields.io/docsrs/blart\n[docs-url]: https://docs.rs/blart/latest/blart/\n\n## Example\n\nHere is an example of using the `TreeMap` type (blatantly stolen from [the standard library][stdlib-example-1]):\n\n```rust\nuse blart::TreeMap;\n\n// type inference lets us omit an explicit type signature (which\n// would be `TreeMap\u003c\u0026str, \u0026str\u003e` in this example).\nlet mut movie_reviews: TreeMap\u003c_, _\u003e = TreeMap::new();\n\n// review some movies.\nlet _ = movie_reviews.try_insert(\"Office Space\",       \"Deals with real issues in the workplace.\").unwrap();\nlet _ = movie_reviews.try_insert(\"Pulp Fiction\",       \"Masterpiece.\").unwrap();\nlet _ = movie_reviews.try_insert(\"The Godfather\",      \"Very enjoyable.\").unwrap();\nlet _ = movie_reviews.try_insert(\"The Blues Brothers\", \"Eye lyked it a lot.\").unwrap();\n\n// check for a specific one.\nif !movie_reviews.contains_key(\"Les Misérables\") {\n    println!(\"We've got {} reviews, but Les Misérables ain't one.\",\n             movie_reviews.len());\n}\n\n// oops, this review has a lot of spelling mistakes, let's delete it.\nmovie_reviews.remove(\"The Blues Brothers\");\n\n// look up the values associated with some keys.\nlet to_find = [\"Up!\", \"Office Space\"];\nfor movie in \u0026to_find {\n    match movie_reviews.get(movie) {\n       Some(review) =\u003e println!(\"{movie}: {review}\"),\n       None =\u003e println!(\"{movie} is unreviewed.\")\n    }\n}\n\n// Look up the value for a key (will panic if the key is not found).\nprintln!(\"Movie review: {}\", movie_reviews[\"Office Space\"]);\n\n// iterate over everything.\nfor (movie, review) in \u0026movie_reviews {\n    println!(\"{movie}: \\\"{review}\\\"\");\n}\n```\n\n[stdlib-example-1]: https://doc.rust-lang.org/stable/std/collections/struct.BTreeMap.html#examples\n\n## Documentation\n\n- [Documentation for the `main` branch][declanvk-blart-docs]\n\n[declanvk-blart-docs]: https://declanvk.github.io/blart/\n\n## Testing\n\n### Miri\n\nCurrently we're using some specific crates (`sptr` and in the future back to `core::ptr::*`) to ensure that we're compatible with [Strict Provenance][sp-issue]. The following `MIRIFLAGS` setup should enable checking to make sure that we're compatible.\n\n```bash\nMIRIFLAGS=\"-Zmiri-strict-provenance -Zmiri-symbolic-alignment-check\" cargo +nightly miri test\n```\n\nI think this is useful because we're doing some pointer times with our tagged pointers implementation, mutating the contents of the pointer to store bits of data.\n\n[sp-issue]: https://github.com/rust-lang/rust/issues/95228\n\n## Fuzzing\n\nTo run the fuzzer I use the command:\n\n```bash\ncargo +nightly fuzz run -j 8 -s address fuzz_tree_map_api -- -max_len=32768 -max_total_time=3600 \u0026\u0026 cargo +nightly fuzz cmin fuzz_tree_map_api\n```\n\nThis will run the fuzzer for a total of 3600 seconds (1 hour), using 8 jobs (half of the total number of cores on my dev box), and using the address sanitizer. The `cmin` command is used to compact the corpus after generating new entries.\n\n### Coverage\n\nTo generate coverage reports from fuzzing corpus:\n\n```bash\n# replace with own triple as required\nTARGET_TRIPLE=\"x86_64-unknown-linux-gnu\"\ncargo +nightly fuzz coverage fuzz_tree_map_api \u0026\u0026 cargo cov -- show fuzz/target/\"$TARGET_TRIPLE\"/release/fuzz_tree_map_api \\\n    --format=html \\\n    -instr-profile=fuzz/coverage/fuzz_tree_map_api/coverage.profdata \\\n    \u003e index.html\n```\n\n```bash\nTARGET_TRIPLE=\"x86_64-unknown-linux-gnu\"\n/home/declan/.rustup/toolchains/nightly-x86_64-unknown-linux-gnu/lib/rustlib/x86_64-unknown-linux-gnu/bin/llvm-cov show -format=html \\\n  -instr-profile=fuzz/coverage/fuzz_tree_map_api/coverage.profdata \\\n  -Xdemangler=rustfilt \\\n  -ignore-filename-regex=\\.cargo/registry \\\n  fuzz/target/x86_64-unknown-linux-gnu/release/fuzz_tree_map_api\n  \u003e cov.html\n\n/home/declan/.rustup/toolchains/nightly-x86_64-unknown-linux-gnu/lib/rustlib/x86_64-unknown-linux-gnu/bin/llvm-cov show \\\n    --instr-profile=/home/declan/repos/github/declanvk/blart/fuzz/coverage/fuzz_tree_map_api/coverage.profdata \\\n    --show-instantiations --show-line-counts-or-regions --Xdemangler=rustfilt \\\n    --format=html --ignore-filename-regex=/home/declan/.cargo/registry --ignore-filename-regex=/home/declan/.rustup/\\\n    target/x86_64-unknown-linux-gnu/coverage/x86_64-unknown-linux-gnu/release/fuzz_tree_map_api \u003e coverage.html\n```\n\n## Benchmarks\n\nTo run the benchmarks, install [`cargo-criterion`][cargo-criterion], then run:\n\n```bash\ncargo +nightly criterion --history-id \"$(git rev-parse --short HEAD)-0\" --features bench-perf-events\n```\n\nor\n\n```bash\ncargo bench --bench \u003cbench_name\u003e --features bench-perf-events\n```\n\nIf you get a \"Permission denied\" error, update perf_event_paranoid:\n```bash\nsudo sh -c 'echo 1 \u003e/proc/sys/kernel/perf_event_paranoid'\n```\nFor further details please take a look at the following [link][superuser-run-perf].\n\n[cargo-criterion]: https://github.com/bheisler/cargo-criterion\n[superuser-run-perf]: https://superuser.com/questions/980632/run-perf-without-root-rights\n\n## Profiling\n\nI use a somewhat realistic benchmark: counting words in a text file. To get started, download a text file like:\n\n```bash\ncurl -o data/Ulysses.txt https://www.gutenberg.org/cache/epub/4300/pg4300.txt\n```\n\nThen build the word count example using the `profiling` profile:\n\n```bash\nRUSTFLAGS=\"-C force-frame-pointers=yes\" cargo build --profile profiling --examples\n```\n\nThen run the count words workload on the downloaded data while profiling:\n\n```bash\nsamply record ./target/profiling/examples/count_words blart data/book-chapters-combined.txt\n```\n\n## License\n\nLicensed under either of\n\n- Apache License, Version 2.0\n  ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)\n- MIT license\n  ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)\n\nat your option.\n\n## Contribution\n\nUnless you explicitly state otherwise, any contribution intentionally submitted\nfor inclusion in the work by you, as defined in the Apache-2.0 license, shall be\ndual licensed as above, without any additional terms or conditions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeclanvk%2Fblart","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdeclanvk%2Fblart","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeclanvk%2Fblart/lists"}