{"id":21452943,"url":"https://github.com/arindas/sangfroid","last_synced_at":"2025-07-04T16:36:18.834Z","repository":{"id":122070236,"uuid":"417759728","full_name":"arindas/sangfroid","owner":"arindas","description":"A load balanced threadpool.","archived":false,"fork":false,"pushed_at":"2022-06-14T16:12:24.000Z","size":3013,"stargazers_count":30,"open_issues_count":0,"forks_count":2,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-08T16:53:42.365Z","etag":null,"topics":["binary-heap","load-balanced","thread-pool"],"latest_commit_sha":null,"homepage":"https://arindas.github.io/sangfroid/sangfroid","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/arindas.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}},"created_at":"2021-10-16T07:58:50.000Z","updated_at":"2024-07-25T13:06:30.000Z","dependencies_parsed_at":null,"dependency_job_id":"0d26b8a4-7504-4b74-81f7-8f42f7cbda66","html_url":"https://github.com/arindas/sangfroid","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/arindas/sangfroid","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arindas%2Fsangfroid","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arindas%2Fsangfroid/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arindas%2Fsangfroid/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arindas%2Fsangfroid/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/arindas","download_url":"https://codeload.github.com/arindas/sangfroid/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arindas%2Fsangfroid/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263577268,"owners_count":23483132,"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":["binary-heap","load-balanced","thread-pool"],"created_at":"2024-11-23T04:33:16.942Z","updated_at":"2025-07-04T16:36:18.829Z","avatar_url":"https://github.com/arindas.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# sangfroid\n[![ci-tests](https://github.com/arindas/sangfroid/actions/workflows/ci-tests.yml/badge.svg)](https://github.com/arindas/sangfroid/actions/workflows/ci-tests.yml)\n[![rustdoc](https://github.com/arindas/sangfroid/actions/workflows/rustdoc.yml/badge.svg)](https://github.com/arindas/sangfroid/actions/workflows/rustdoc.yml)\n[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Farindas%2Fsangfroid.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2Farindas%2Fsangfroid?ref=badge_shield)\n\nA load balanced thread pool.\n\n## How does it work?\n\nWe maintain a binary heap of worker threads. Worker threads are ordered by the number of\npending tasks associated with it. Whenever a new job is scheduled, we pick up the least\nloaded worker and dispatch the job to it. We update its pending task count and restore\nthe heap accordingly.\n\nWhen a worker is done executing a job, it sends its Uid to the done channel. A background\nbalancer thread continuously receives on this channel until it receives a None value.\nWhen the balancer thread receives an uid, it looks up the associated worker from the\nworker pool heap, decrements it's load and restores the heap accordingly.\n\nAll communication to and from threads is done via channels. We use locks as sparingly as\npossible. More specifically, we only lock on the binary heap in the thread pool with a\nMutex since it is also used by the balancer thread.\nWe stay true to the concept:\n\u003eDo not communicate by sharing memory; instead, share memory by communicating.\n\n```rust\n//! example 0: basic api usage\nlet thread_pool = ThreadPool::\u003cu8, u8\u003e::new(1);\n\nlet (job, result_src) = Job::with_result_sink(|x| x * 2, 2);\nthread_pool.schedule(job).expect(\"job not scheduled\");\nassert_eq!(result_src.recv().unwrap(), 4);\n\n//! example 1: with shared resource\nlet shared_hashmap = Arc::new(RwLock::new(HashMap::\u003cu8, u8\u003e::new()));\nconst PLACE_HOLDER: u8 = 5;\n\nassert_eq!(shared_hashmap.read().unwrap().get(\u00261), None);\n\nlet thread_pool = ThreadPool::\u003c((u8, u8), Arc\u003cRwLock\u003cHashMap\u003cu8, u8\u003e\u003e\u003e), ()\u003e::new(2);\n\nlet job = Job::new(\n    |((key, value), shared_map)| {\n        shared_map.write().unwrap().insert(key, value);\n    },\n    ((1, 2), Arc::clone(\u0026shared_hashmap)),\n);\nthread_pool.schedule(job).expect(\"job not scheduled\");\n\nlet job = Job::new(\n    |((key, _), shared_map)| {\n        shared_map.read().unwrap().get(\u0026key);\n    },\n    ((1, PLACE_HOLDER), Arc::clone(\u0026shared_hashmap)),\n);\nthread_pool.schedule(job).expect(\"job not scheduled\");\n\n// wait some time for writers to finish\nthread::sleep(Duration::from_secs(1));\n\nassert_eq!(shared_hashmap.read().unwrap().get(\u00261), Some(\u00262));\n```\n\nRefer to [API documentation](https://arindas.github.io/sangfroid/sangfroid) for more details.\n\n### Why did you make this?\nThis crate was inspired from the load balancer described in the excellent\n[\"Concurrency is not Parallelism\"](https://youtu.be/oV9rvDllKEg) talk by Rob Pike.\n\n### Well, did you learn anything?\nThread management and synchorization in Rust. I was also able to improve my ownership concepts.\nThis was a great project for applying the knowledge I assimilated from the aforementioned\ntalk and improve my ability to express my ideas in `Rust`.\n\n## Dependencies\nThis does not depend on any third party crates. The only dependency is the\n[`bheap`](https://github.com/arindas/bheap) crate, which I wrote for managing the workers.\n\n## Usage\nThis is a library crate. You may include it in your `Cargo.toml` as follows:\n```toml\n[dependencies]\nsangfroid = { git = \"https://github.com/arindas/sangfroid\" }\n```\n\n### Why the weird name?\n\u003esangfroid /sɒ̃ˈfrwɑː/ noun;\n\u003ecomposure or coolness shown in danger or under trying circumstances.\n\nI found it fitting.\n\n## LICENSE\n`sangfroid` is licensed under the MIT License. See [LICENSE](./LICENSE) for the full license text.\n\n[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Farindas%2Fsangfroid.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2Farindas%2Fsangfroid?ref=badge_large)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farindas%2Fsangfroid","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farindas%2Fsangfroid","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farindas%2Fsangfroid/lists"}