{"id":13550199,"url":"https://github.com/bastion-rs/agnostik","last_synced_at":"2025-04-05T19:12:28.559Z","repository":{"id":52414260,"uuid":"238682706","full_name":"bastion-rs/agnostik","owner":"bastion-rs","description":"Executor Agnostic Runtime that can run your futures with your favourite Executor","archived":false,"fork":false,"pushed_at":"2021-04-29T21:16:11.000Z","size":158,"stargazers_count":143,"open_issues_count":8,"forks_count":11,"subscribers_count":9,"default_branch":"master","last_synced_at":"2024-10-29T22:37:26.167Z","etag":null,"topics":["agnostic-runtime","einheit-in-vielfalt","executor-agnostic"],"latest_commit_sha":null,"homepage":"https://docs.rs/agnostik","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/bastion-rs.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}},"created_at":"2020-02-06T12:21:36.000Z","updated_at":"2024-10-25T20:40:29.000Z","dependencies_parsed_at":"2022-09-26T16:31:16.358Z","dependency_job_id":null,"html_url":"https://github.com/bastion-rs/agnostik","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bastion-rs%2Fagnostik","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bastion-rs%2Fagnostik/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bastion-rs%2Fagnostik/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bastion-rs%2Fagnostik/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bastion-rs","download_url":"https://codeload.github.com/bastion-rs/agnostik/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247386265,"owners_count":20930619,"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":["agnostic-runtime","einheit-in-vielfalt","executor-agnostic"],"created_at":"2024-08-01T12:01:30.091Z","updated_at":"2025-04-05T19:12:28.531Z","avatar_url":"https://github.com/bastion-rs.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"# Agnostik\n\n[![Crates.io](https://img.shields.io/crates/v/agnostik)](https://crates.io/crates/agnostik)\n[![doc](https://img.shields.io/badge/rustdoc-agnostik-blue.svg)](https://docs.rs/agnostik)\n[![CI](https://github.com/bastion-rs/agnostik/workflows/CI/badge.svg)](https://github.com/bastion-rs/agnostik/actions)\n\nAgnostik is a layer between your application and the executor for your async stuff.\nIt lets you switch the executors smooth and easy without having to change your applications code.\n\n## Features\n\n- Run futures and wait for them to finish\n- Spawn Futures using the underlying executor\n- Spawn blocking tasks using special threads that are able to execute blocking code\n\n## Get started\n\nCheck the [tests](https://github.com/bastion-rs/agnostik/tree/master/tests) for simple examples.\n\nIf you have [cargo-edit](https://github.com/killercup/cargo-edit) installed, you can just execute \nthis:\n```\ncargo add agnostik\n```\n\notherwise, add this to your Cargo.toml file\n```\nagnostik = \"0.2\"\n```\n\n## Usage\n\n### Switching executors\n\n**Note:** Libraries should not enable any runtime feature.\nYou can choose the executor, by using cargo features.\nThere can only be one enabled runtime.\nValid features are: \n- `runtime_bastion` to use the [Bastion Executor](https://crates.io/crates/bastion-executor)\n- `runtime_tokio` to use the [Tokio version \u003e0.3.4](https://tokio.rs) runtime\n- `runtime_tokio1` to use the [Tokio version 1.*](https://tokio.rs) runtime\n- `runtime_asyncstd` to use the [AsyncStd](https://async.rs) runtime\n- `runtime_smol` to use the new and awesome [smol](https://docs.rs/smol) runtime\n\nE.g. to use the Tokio runtime, add the following line to your Cargo.toml\n```\nagnostik = { version = \"0.2\", features = [\"runtime_tokio\"]}\n```\n\n### Examples\n\nAgnostiks API is very easy and only has a few methods to use.\nHere's an example with the bastion-executor.\n\n```rust\nuse agnostik::prelude::*;\n\nfn main() {\n    let runtime = Agnostik::bastion();\n\n    let future = runtime.spawn(async {\n        println!(\"Hello from bastions executor!\");\n    })\n    runtime.block_on(future)\n    \n    let future = runtime.spawn_blocking(|| {\n        expensive_blocking_method();\n    })\n    runtime.block_on(future)\n}\n```\n\n\nThere's also a global executor instance that can be used to spawn futures\nwithout creating and storing your own executor.\nIf you specify multiple runtimes, the global executor will be the following:\n- `smol` if `tokio` and `smol` are enabled\n- `bastion` if `async_std`, `smol` and / or `tokio` is enabled\n\n```rust\nfn main() {\n    let future = agnostik::spawn(async { println!(\"Hello from bastion executor!\"); 1 });\n    let result = agnostik::block_on(future);\n    assert_eq!(result, 1);\n}\n```\n\nIf you want to use another executor, you just have to replace the `Agnostik::bastion()`\nmethod call, with the method that corresponds to your executor.\n\nUse\n- `Agnostik::bastion()` for bastion\n- `Agnostik::async_std()` for async std\n- `Agnostik::tokio()` for tokio. **Warning:** See \"How to use tokio runtime\"\n- `Agnostik::tokio_with_runtime(runtime)` if you want to use your own `tokio::runtime::Runtime` object. **Warning:** See \"How to use tokio runtime\"\n- `Agnostik::no_std()` (coming soon) to create an exeutor that works in a nostd environment\n\n### How to use tokio runtime\n\nIt's not supported to use the `tokio::main` macro together with agnostik,\nbecause Agnostik requires a `Runtime` object, which is created by calling `Runtime::new()`.\nIf your are using the `tokio::main` macro, there will be a panic, because you can't create a runtime\ninside a runtime.\n\nHere's how to fix it:\n\n```rust\nuse agnostik::prelude::*;\n\n#[tokio::main]\nasync fn main() {\n    let runtime = Agnostik::tokio();\n    \n    let result = runtime.spawn(async_task()).await;\n\n    println!(\"The result is {}\", result)\n}\n```\n\nThis would fail with a panic.\nHow to do it correctly:\n\n```rust\nuse agnostik::prelude::*;\nuse tokio::runtime::Runtime;\n\nfn main() {\n    // see tokio docs for more methods to create a runtime\n    let runtime = Runtime::new().expect(\"Failed to create a runtime\"); // 1\n    let runtime = Agnostik::tokio_with_runtime(runtime); // 2\n\n    let result = runtime.spawn(async_task());\n    let result = runtime.block_on(result);\n\n    println!(\"The result is {}\", result)\n}\n```\n\nYou can replace 1 and 2 with `Agnostik::tokio()`, because this method call will\ncreate a Runtime object using `Runtime::new()`.\n\n### Getting Help\n\nPlease head to our [Discord](https://discord.gg/DqRqtRT).\n\n### License\n\nThis project is licensed under the Apache2 or MIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbastion-rs%2Fagnostik","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbastion-rs%2Fagnostik","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbastion-rs%2Fagnostik/lists"}