{"id":13821190,"url":"https://github.com/acl-dev/open-coroutine","last_synced_at":"2025-04-30T21:31:13.207Z","repository":{"id":37824615,"uuid":"494935111","full_name":"acl-dev/open-coroutine","owner":"acl-dev","description":"The open-coroutine is a simple, efficient and generic stackful-coroutine library.","archived":false,"fork":false,"pushed_at":"2024-04-24T09:22:39.000Z","size":132107,"stargazers_count":19,"open_issues_count":1,"forks_count":4,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-05-21T00:59:36.192Z","etag":null,"topics":["coroutine","hook","rust"],"latest_commit_sha":null,"homepage":"","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/acl-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"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-05-22T01:51:17.000Z","updated_at":"2024-06-15T07:25:21.044Z","dependencies_parsed_at":"2023-11-11T12:22:50.605Z","dependency_job_id":"8d1b706d-7345-4862-9380-f4e824cfca2e","html_url":"https://github.com/acl-dev/open-coroutine","commit_stats":{"total_commits":412,"total_committers":5,"mean_commits":82.4,"dds":0.1189320388349514,"last_synced_commit":"fbb29cf274df11bd072fdd1af710749963b43411"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acl-dev%2Fopen-coroutine","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acl-dev%2Fopen-coroutine/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acl-dev%2Fopen-coroutine/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acl-dev%2Fopen-coroutine/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/acl-dev","download_url":"https://codeload.github.com/acl-dev/open-coroutine/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223564727,"owners_count":17165988,"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":["coroutine","hook","rust"],"created_at":"2024-08-04T08:01:17.131Z","updated_at":"2025-04-30T21:31:13.195Z","avatar_url":"https://github.com/acl-dev.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"# open-coroutine\n\n[![crates.io](https://img.shields.io/crates/v/open-coroutine.svg)](https://crates.io/crates/open-coroutine)\n[![docs.rs](https://img.shields.io/badge/docs-release-blue)](https://docs.rs/open-coroutine)\n[![LICENSE](https://img.shields.io/github/license/acl-dev/open-coroutine.svg?style=flat-square)](https://github.com/acl-dev/open-coroutine/blob/master/LICENSE-APACHE)\n[![Build Status](https://github.com/acl-dev/open-coroutine/workflows/CI/badge.svg)](https://github.com/acl-dev/open-coroutine/actions)\n[![Codecov](https://codecov.io/github/acl-dev/open-coroutine/graph/badge.svg?token=MSM3R7CBEX)](https://codecov.io/github/acl-dev/open-coroutine)\n[![Average time to resolve an issue](http://isitmaintained.com/badge/resolution/acl-dev/open-coroutine.svg)](http://isitmaintained.com/project/acl-dev/open-coroutine \"Average time to resolve an issue\")\n[![Percentage of issues still open](http://isitmaintained.com/badge/open/acl-dev/open-coroutine.svg)](http://isitmaintained.com/project/acl-dev/open-coroutine \"Percentage of issues still open\")\n\nThe `open-coroutine` is a simple, efficient and generic stackfull-coroutine library, you can use this as a performance\nreplacement for IO thread pools, see [why better](core/docs/en/why-better.md).\n\nEnglish | [中文](README_ZH.md)\n\n## 🚀 Features\n\n- [x] Preemptive(`not supported in windows`): even if the coroutine enters a dead loop, it can still be seized,\n  see [example](https://github.com/loongs-zhang/open-coroutine/blob/master/open-coroutine/examples/preemptive.rs);\n- [x] Hook: you are free to use most of the slow syscall in coroutine, see supported syscall\n  on [unix](https://github.com/acl-dev/open-coroutine/blob/master/hook/src/syscall/unix.rs)/[windows](https://github.com/acl-dev/open-coroutine/blob/master/hook/src/syscall/windows.rs);\n- [x] Scalable: the size of the coroutine stack supports unlimited expansion without the cost of copying stack, and\n  immediately shrinks to the original size after use,\n  see [example](https://github.com/loongs-zhang/open-coroutine/blob/master/open-coroutine/examples/scalable_stack.rs);\n- [x] io_uring(`only in linux`): supports and is compatible with io_uring in terms of local file IO and network IO. If\n  it's not supported on your system, it will fall back to non-blocking IO;\n- [x] Priority: support custom task priority, note that coroutine priority is not open to users;\n- [x] Work Steal: internally using a lock free work steal queue;\n- [x] Compatibility: the implementation of open-coroutine is no async, but it is compatible with async, which means you\n  can use this crate in `tokio/async-std/smol/...`;\n- [x] Platforms: running on Linux, macOS and Windows;\n\n## 🕊 Roadmap\n\n- [ ] add\n  performance [benchmark](https://github.com/TechEmpower/FrameworkBenchmarks/wiki/Project-Information-Framework-Tests-Overview);\n- [ ] add metrics;\n- [ ] add synchronization toolkit;\n- [ ] support and compatibility for AF_XDP socket;\n\n## 🏠 Architecture\n\n```mermaid\ngraph TD\n    subgraph ApplicationFramework\n        Tower\n        Actix-Web\n        Rocket\n        warp\n        axum\n    end\n    subgraph MessageQueue\n        RocketMQ\n        Pulsar\n    end\n    subgraph RemoteProcedureCall\n        Dubbo\n        Tonic\n        gRPC-rs\n        Volo\n    end\n    subgraph Database\n        MySQL\n        Oracle\n    end\n    subgraph NetworkFramework\n        Tokio\n        monoio\n        async-std\n        smol\n    end\n    subgraph open-coroutine-architecture\n        subgraph core\n            Preemptive\n            ScalableStack\n            WorkSteal\n            Priority\n        end\n        subgraph hook\n            HookSyscall\n        end\n        subgraph macros\n            open-coroutine::main\n        end\n        subgraph open-coroutine\n        end\n        hook --\u003e|depends on| core\n        open-coroutine --\u003e|link| hook\n        open-coroutine --\u003e|depends on| macros\n    end\n    subgraph OperationSystem\n        Linux\n        macOS\n        Windows\n    end\n    ApplicationFramework --\u003e|maybe depends on| RemoteProcedureCall\n    ApplicationFramework --\u003e|maybe depends on| MessageQueue\n    ApplicationFramework --\u003e|maybe depends on| Database\n    MessageQueue --\u003e|depends on| NetworkFramework\n    RemoteProcedureCall --\u003e|depends on| NetworkFramework\n    NetworkFramework --\u003e|runs on| OperationSystem\n    NetworkFramework --\u003e|can depends on| open-coroutine-architecture\n    Database --\u003e|runs on| OperationSystem\n    open-coroutine-architecture --\u003e|runs on| OperationSystem\n```\n\n## 📖 Quick Start\n\n### step1: add dependency to your Cargo.toml\n\n```toml\n[dependencies]\n# check https://crates.io/crates/open-coroutine\nopen-coroutine = \"x.y.z\"\n```\n\n### step2: add `open_coroutine::main` macro\n\n```rust\n#[open_coroutine::main]\nfn main() {\n    //......\n}\n```\n\n### step3: create a task\n\n```rust\n#[open_coroutine::main]\nfn main() {\n    _ = open_coroutine::task!(|param| {\n        assert_eq!(param, \"param\");\n    }, \"param\");\n}\n```\n\n## 🪶 Advanced Usage\n\n### create a task with priority\n\n```rust\n#[open_coroutine::main]\nfn main() {\n    _ = open_coroutine::task!(|param| {\n        assert_eq!(param, \"param\");\n    }, \"param\", 1/*the smaller the value, the higher the priority*/);\n}\n```\n\n### wait until the task is completed or timed out\n\n```rust\n#[open_coroutine::main]\nfn main() {\n    let task = open_coroutine::task!(|param| {\n        assert_eq!(param, \"param\");\n    }, \"param\", 1);\n    task.timeout_join(std::time::Duration::from_secs(1)).expect(\"timeout\");\n}\n```\n\n### wait until any task is completed or timed out\n\n```rust\n#[open_coroutine::main]\nfn main() {\n    let result = open_coroutine::any_timeout_join!(\n        std::time::Duration::from_secs(1),\n        open_coroutine::task!(|_| 1, ()),\n        open_coroutine::task!(|_| 2, ()),\n        open_coroutine::task!(|_| 3, ())\n    ).expect(\"timeout\");\n}\n```\n\n### scalable stack\n\n```rust\n#[open_coroutine::main]\nfn main() {\n    _ = open_coroutine::task!(|_| {\n        fn recurse(i: u32, p: \u0026mut [u8; 10240]) {\n            open_coroutine::maybe_grow!(|| {\n                // Ensure the stack allocation isn't optimized away.\n                unsafe { _ = std::ptr::read_volatile(\u0026p) };\n                if i \u003e 0 {\n                    recurse(i - 1, \u0026mut [0; 10240]);\n                }\n            })\n            .expect(\"allocate stack failed\")\n        }\n        println!(\"[task] launched\");\n        // Use ~500KB of stack.\n        recurse(50, \u0026mut [0; 10240]);\n    }, ());\n}\n```\n\n## ⚓ Learn More\n\n- [Project Overview](core/docs/en/overview.md)\n- [Background](docs/en/background.md)\n- [Why Rust](docs/en/why-rust.md)\n- [Coroutine Overview](core/docs/en/coroutine.md)\n- [Scalable Stack Overview](core/docs/en/scalable-stack.md)\n- [Monitor Overview](core/docs/en/monitor.md)\n- [Work Steal Overview](core/docs/en/work-steal.md)\n- [Ordered Work Steal Overview](core/docs/en/ordered-work-steal.md)\n- [Coroutine Pool Overview](core/docs/en/coroutine-pool.md)\n- [Hook Overview](hook/docs/en/hook.md)\n\n[Old Docs Here](https://github.com/acl-dev/open-coroutine-docs)\n\n## 👍 Credits\n\nThis crate was inspired by the following projects:\n\n- [acl](https://github.com/acl-dev/acl)\n- [coost](https://github.com/idealvin/coost)\n- [golang](https://github.com/golang/go)\n- [stacker](https://github.com/rust-lang/stacker)\n- [monoio](https://github.com/bytedance/monoio)\n- [compio](https://github.com/compio-rs/compio)\n- [may](https://github.com/Xudong-Huang/may)\n\nThanks to those who have provided assistance:\n\n[![Amanieu](https://images.weserv.nl/?url=avatars.githubusercontent.com/Amanieu?v=4\u0026h=79\u0026w=79\u0026fit=cover\u0026mask=circle\u0026maxage=7d)](https://github.com/Amanieu)\n[![bjorn3](https://images.weserv.nl/?url=avatars.githubusercontent.com/bjorn3?v=4\u0026h=79\u0026w=79\u0026fit=cover\u0026mask=circle\u0026maxage=7d)](https://github.com/bjorn3)\n[![workingjubilee](https://images.weserv.nl/?url=avatars.githubusercontent.com/workingjubilee?v=4\u0026h=79\u0026w=79\u0026fit=cover\u0026mask=circle\u0026maxage=7d)](https://github.com/workingjubilee)\n[![Noratrieb](https://images.weserv.nl/?url=avatars.githubusercontent.com/Noratrieb?v=4\u0026h=79\u0026w=79\u0026fit=cover\u0026mask=circle\u0026maxage=7d)](https://github.com/Noratrieb)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Facl-dev%2Fopen-coroutine","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Facl-dev%2Fopen-coroutine","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Facl-dev%2Fopen-coroutine/lists"}