{"id":27276476,"url":"https://github.com/folo-rs/folo","last_synced_at":"2025-09-15T07:04:51.783Z","repository":{"id":255437280,"uuid":"850321188","full_name":"folo-rs/folo","owner":"folo-rs","description":"Mechanisms for high-performance hardware-aware programming in Rust","archived":false,"fork":false,"pushed_at":"2025-09-09T03:39:48.000Z","size":4815,"stargazers_count":27,"open_issues_count":6,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-09T04:02:52.398Z","etag":null,"topics":["rust"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/folo-rs.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":"2024-08-31T13:00:11.000Z","updated_at":"2025-09-09T03:39:15.000Z","dependencies_parsed_at":"2024-09-18T11:07:09.358Z","dependency_job_id":"7cb93d58-979a-4341-b3aa-f704af2e0332","html_url":"https://github.com/folo-rs/folo","commit_stats":null,"previous_names":["sandersaares/folo","folo-rs/folo"],"tags_count":514,"template":false,"template_full_name":null,"purl":"pkg:github/folo-rs/folo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/folo-rs%2Ffolo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/folo-rs%2Ffolo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/folo-rs%2Ffolo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/folo-rs%2Ffolo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/folo-rs","download_url":"https://codeload.github.com/folo-rs/folo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/folo-rs%2Ffolo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274448918,"owners_count":25287139,"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","status":"online","status_checked_at":"2025-09-10T02:00:12.551Z","response_time":83,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["rust"],"created_at":"2025-04-11T16:14:12.718Z","updated_at":"2025-09-15T07:04:51.757Z","avatar_url":"https://github.com/folo-rs.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"# Folo\n\nMechanisms for high-performance hardware-aware programming in Rust.\n\n# What it gives you\n\n![](doc/hardware.png)\n\nTo take advantage of hardware-awareness we must first gain that awareness.\n[`many_cpus`][many_cpus] informs us about the nature of the system's processors and\n[the arrangement of them in relation to main memory][numa], giving us control over what\nspecific logic runs on which specific processors. No longer do we simply `thread::spawn()`\nblindly - now we spawn specific threads for specific processors or groups of processors.\n\n[`many_cpus_benchmarking`][many_cpus_b] provides a benchmark harness to explore the effects of\nhow work and data are spread between processors, when applied to different algorithms. This\nallows you to judge when it matters and by how much.\n\n![](doc/region_cached.png)\n\n[The ability to target our workloads to specific processors and specific memory regions unlocks new optimization opportunities.][structural_changes]\n[`region_local`][region_local] and [`region_cached`][region_cached]\nprovide something like a layer of caching between the processor and main memory, ensuring that\neven data sets that do not fit into processor caches still experience high data locality.\n\n![](doc/linked.png)\n\nDesigning code for hardware-efficiency often benefits from a thread-isolated mindset, treating\neach thread as its own universe. [`linked`][linked] provides valuable concepts, metaphors and\nmechanisms to enable objects to present a unique face to each thread, acting as separate objects\non each thread while being connected through internal logic and only permitting opt-in transfers\nacross thread boundaries. These are the building blocks used to implement `region_local` and\n`region_cached`.\n\nMeasuring effects of hardware-aware programming sometimes requires benchmarks to be multi-threaded,\nwhich is not something you get out of the box with benchmark frameworks like [Criterion][criterion].\n[`par_bench`][par_bench] extends Criterion with a simple harness for multithreaded benchmarking,\nrunning your benchmark logic on a specific processor set obtained from `many_cpus`. It takes care\nof all the dirty business involved in coordinating the threads and eliminating any test harness\noverhead from the data.\n\n```\nProcessor time statistics:\n\n| Operation                   | Mean |\n|-----------------------------|------|\n| futures_oneshot_channel_mt  | 92ns |\n| futures_oneshot_channel_st  | 76ns |\n| local_once_event_managed    | 38ns |\n| pooled_local_once_event_ptr | 27ns |\n| pooled_local_once_event_rc  | 31ns |\n| pooled_local_once_event_ref | 24ns |\n```\n\nWhen evaluating complex application logic, it can be important to take a holistic view - it does\nnot only matter how fast the benchmark logic runs but also how much energy (processor time) it\nuses. Perhaps the code also runs logic on background threads or perhaps the code just blocks\nsome threads for a while on syscalls, costing wall clock time without costing processor time.\nThese are all factors that we must account for in complex scenarios. [`all_the_time`][all_the_time]\nallows us to track the processor time spent by the process, in addition to the wall clock time.\nIt integrates well into Criterion and is natively supported by `par_bench`.\n\n```\nAllocation statistics:\n\n| Operation                      | Mean bytes | Mean count |\n|--------------------------------|------------|------------|\n| futures_oneshot_channel        |        128 |          1 |\n| local_once_event_managed       |         48 |          1 |\n| pooled_local_once_event_ptr    |          0 |          0 |\n| pooled_local_once_event_rc     |          0 |          0 |\n| pooled_local_once_event_ref    |          0 |          0 |\n```\n\nMemory allocation is the root of all evil. The simplest and most effective way to make a typical\napplication faster is to eliminate memory allocations from it - this can often multiply performance\nseveral times. Before we can eliminate, we need to measure. [`alloc_tracker`][alloc_tracker] gives\nus the ability to measure exactly how much heap memory is allocated by a particular piece of code.\nIt integrates well into Criterion and is natively supported by `par_bench`.\n\nOnce we have knowledge of how much memory we are allocating, we can start making a difference. The\nsimplest way is to change the algorithms so no memory allocations are necessary but sometimes that\nis impractical. Nevertheless, the global Rust memory allocator (whichever one might be used) is a\ngeneral-purpose mechanism and it pays a price in performance for that generality. If we are\nallocating a large number of objects of specific sizes, we can benefit from special-purpose\nallocators that keep the memory around for reuse, so the next allocation is simple and fast.\n\nWhile allocator APIs are still an unstable Rust feature, there are stable-API alternatives.\nAnother term for special-purpose allocators is object pools and [`infinity_pool`][infinity_pool]\noffers several of them, from basic `Vec\u003cT\u003e` style pinned object collections to type-agnostic object\npools that can allocate any type of object. While the safe-API variants come with substantial\noverheads compared to the unsafe-API variants, they both can surpass the efficiency of using the\nglobal memory allocator under many conditions. Your mileage may vary - measure 100 times,\ncut 10 times.\n\nA surprising source of memory allocations in high-performance code can be signaling. We are used\nto thinking of oneshot channels as cheap and efficient things and while this is true, they are\nstill built upon shared memory allocated from the heap. Every signaling channel you create is a\nheap allocation and they can add up fast! [`events`][events] provides you with pooled signaling\nchannels that take advantage of `infinity_pool` to reuse memory allocations, as well as providing\nsingle-threaded and unsafe-code-managed events for lower overhead in specialized scenarios.\n\n```\nbagels_cooked_weight_grams: 2300; sum 744000; mean 323\nvalue \u003c=    0 [    0 ]: \nvalue \u003c=  100 [    0 ]: \nvalue \u003c=  200 [ 1300 ]: ∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎\nvalue \u003c=  300 [    0 ]: \nvalue \u003c=  400 [    0 ]: \nvalue \u003c=  500 [    0 ]: \nvalue \u003c=  600 [ 1000 ]: ∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎∎\nvalue \u003c=  700 [    0 ]: \nvalue \u003c=  800 [    0 ]: \nvalue \u003c=  900 [    0 ]: \nvalue \u003c= 1000 [    0 ]: \nvalue \u003c= +inf [    0 ]: \n```\n\nIt is easy to think that performance and efficiency has been achieved once the benchmarks look good. \nYet time makes fools of us all! Real-world data often shows surprising behaviors - where we thought\nwe would spawn 500 tasks, a surprise implementation detail from the HTTP stack may end up spawning\n500 million! Benchmarks and belief is not enough. [`nm`][nm] provides a very high performance\nand minimal metrics framework suitable for taking millions of measurements per second. Only with\nthe real data can we be assured that we achieve real performance.\n\nMany attempts to instrument high-performance logic are self-defeating because few people expect\nthat time itself is slow. Measuring the time, that is! `Instant::now()` is a remarkably slow\noperation - never use this in high-performance code, as merely capturing the timestamp can massively\ndegrade performance. Accurate timing information can only ever be measured for large batches of\niterations so that one measurement span covers 100+ milliseconds of work. For situations where you\ncan sacrifice precision but still want satisfactory performance, [`fast_time`][fast_time] provides\na clock that is much cheaper to query. It will not give you precise numbers but it is safe to\nquery tens of thousands of times per second.\n\n\n# Extras\n\nAuxiliary packages developed and published by this project:\n\n* `cargo-detect-package` - cargo subcommand to detect which package is used based on a provided path and to run another subcommand on that package.\n* `cpulist` - utilities for parsing and emitting Linux cpulist strings, used by `many_cpus`.\n* `new_zealand` - [utilities for working with non-zero integers][nonzero].\n\nPackages present in the repo but not relevant to a general audience:\n\n* `benchmarks` - random pile of benchmarks to explore relevant scenarios and guide Folo development.\n* `folo_ffi` - utilities for working with FFI logic; exists for internal use in Folo packages; no stable API surface.\n* `folo_utils` - utilities for internal use in Folo packages; exists for internal use in Folo packages; no stable API surface.\n* `testing` - private helpers for testing and examples in Folo packages.\n\nDeprecated packages:\n\n* `blind_pool` - deprecated, use `infinity_pool` which offers a similar API but is internally structured in a more maintainable manner.\n* `opaque_pool` - deprecated, use `infinity_pool` which offers a similar API but is internally structured in a more maintainable manner.\n* `pinned_pool` - deprecated, use `infinity_pool` which offers a similar API but is internally structured in a more maintainable manner.\n\n[all_the_time]: packages/all_the_time/README.md\n[alloc_tracker]: packages/alloc_tracker/README.md\n[criterion]: https://bheisler.github.io/criterion.rs/book/criterion_rs.html\n[events]: packages/events/README.md\n[fast_time]: packages/fast_time/README.md\n[infinity_pool]: packages/infinity_pool/README.md\n[linked]: packages/linked/README.md\n[many_cpus]: packages/many_cpus/README.md\n[many_cpus_b]: packages/many_cpus_benchmarking/README.md\n[nm]: packages/nm/README.md\n[nonzero]: https://github.com/rust-lang/rfcs/pull/3786\n[numa]: https://www.kernel.org/doc/html/v4.18/vm/numa.html\n[par_bench]: packages/par_bench/README.md\n[region_cached]: packages/region_cached/README.md\n[region_local]: packages/region_local/README.md\n[structural_changes]: https://sander.saares.eu/2025/03/31/structural-changes-for-48-throughput-in-a-rust-web-service/\n\n# Development environment setup\n\nSee [DEVELOPMENT.md](DEVELOPMENT.md).\n\n# Quality assurance\n\nThis project aims for high quality standards:\n\n✅ **Comprehensive testing** - All packages tested with extensive unit tests, integration tests, and doctests  \n✅ **Miri validation** - All packages pass strict Rust memory safety validation via Miri  \n✅ **Mutation testing** - Code quality verified through comprehensive mutation testing with `cargo-mutants`  \n✅ **High test coverage** - Test coverage measured and maintained via `cargo-llvm-cov`  \n✅ **Zero warnings policy** - All code must compile without any compiler or Clippy warnings  \n✅ **Extensive Clippy rules** - 100+ custom Clippy lint rules enforced across the workspace  \n✅ **Cross-platform validation** - All code tested on both Windows and Linux platforms  \n✅ **Automated CI/CD** - Continuous integration runs full validation suite on every commit  \n✅ **API documentation** - Complete API documentation with inline examples for all public APIs  \n✅ **Dependency auditing** - Regular security audits of all dependencies via `cargo-audit`  \n✅ **Semver compliance** - API changes validated for semantic versioning compliance via `cargo-semver-checks`","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffolo-rs%2Ffolo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffolo-rs%2Ffolo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffolo-rs%2Ffolo/lists"}