{"id":16867006,"url":"https://github.com/thomasdezeeuw/heph","last_synced_at":"2025-05-16T11:04:45.625Z","repository":{"id":40446477,"uuid":"113782145","full_name":"Thomasdezeeuw/heph","owner":"Thomasdezeeuw","description":"Heph is an actor library for Rust based on asynchronous functions.","archived":false,"fork":false,"pushed_at":"2025-03-01T16:47:36.000Z","size":3909,"stargazers_count":140,"open_issues_count":62,"forks_count":8,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-09T11:19:10.069Z","etag":null,"topics":["actor-model","actors","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/Thomasdezeeuw.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2017-12-10T20:45:22.000Z","updated_at":"2025-03-14T03:59:09.000Z","dependencies_parsed_at":"2023-11-24T23:23:21.930Z","dependency_job_id":"fac84d00-d6f3-4908-9c36-fd5b02acf6c6","html_url":"https://github.com/Thomasdezeeuw/heph","commit_stats":{"total_commits":2521,"total_committers":3,"mean_commits":840.3333333333334,"dds":0.0007933359777866356,"last_synced_commit":"646952bb3956f5dc980e24b9dc403f6edc71f230"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Thomasdezeeuw%2Fheph","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Thomasdezeeuw%2Fheph/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Thomasdezeeuw%2Fheph/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Thomasdezeeuw%2Fheph/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Thomasdezeeuw","download_url":"https://codeload.github.com/Thomasdezeeuw/heph/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254518384,"owners_count":22084374,"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":["actor-model","actors","rust"],"created_at":"2024-10-13T14:52:23.254Z","updated_at":"2025-05-16T11:04:40.615Z","avatar_url":"https://github.com/Thomasdezeeuw.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Heph\n\nHeph, derived from [Hephaestus], is the Greek god of blacksmiths, metalworking,\ncarpenters, craftsmen, artisans, sculptors, metallurgy, fire, and volcanoes.\nWell this crate has very little to do with Greek gods, but I needed a name.\n\nQuick links:\n\n| Crate       | [crates.io](https://crates.io)                      | [docs.rs](https://docs.rs)                 |\n| ----------- | --------------------------------------------------- | ------------------------------------------ |\n| Heph        | [heph](https://crates.io/crates/heph)               | [heph](https://docs.rs/heph)               |\n| Heph-rt     | [heph-rt](https://crates.io/crates/heph-rt)         | [heph-rt](https://docs.rs/heph-rt)         |\n| Heph-http   | [heph-http](https://crates.io/crates/heph-http)     | [heph-http](https://docs.rs/heph-http)     |\n| Heph-remote | [heph-remote](https://crates.io/crates/heph-remote) | [heph-remote](https://docs.rs/heph-remote) |\n| Heph-inbox  | [heph-inbox](https://crates.io/crates/heph-inbox)   | [heph-inbox](https://docs.rs/heph-inbox)   |\n\n[Hephaestus]: https://en.wikipedia.org/wiki/Hephaestus\n\n\n## About\n\nHeph is an [actor] framework based on asynchronous functions. Such an\nasynchronous function looks like this:\n\n```rust\nasync fn actor(mut ctx: actor::Context\u003cString, ThreadLocal\u003e) {\n    // Receive a message.\n    let msg = ctx.receive_next().await;\n    // Print the message.\n    println!(\"got a message: {msg}\");\n}\n```\n\nFor more examples see the [examples] directory.\n\n[actor]: https://en.wikipedia.org/wiki/Actor_model\n[examples]: ./examples/README.md\n\n\n## Design\n\nHeph uses event-driven scheduling, non-blocking I/O (utiling io\\_uring) and a\nshare nothing design. But what do all those buzzwords actually mean?\n\n - *Event-driven*: Heph does nothing by itself, it must first get an event\n   before it starts doing anything. For example an actor is only run when it\n   receives a message or I/O has been completed.\n - *Non-blocking I/O*: normal I/O operations need to wait (block) until the\n   operation can complete. Using non-blocking, or asynchronous, I/O means that\n   rather than waiting for the operation to complete we'll do some other more\n   useful work and try the operation later. Furthermore using io\\_uring we don't\n   even have to make system calls (to do I/O) anymore!\n - *Share nothing*: many applications share data across multiple threads. To\n   do this safely, we need to protect it from data races via a [`Mutex`] or\n   by using [atomic] operations. Heph is designed to not share any data. Each\n   actor is responsible for its own memory and cannot access memory owned by\n   other actors. Instead, communication is done via sending messages–see [actor\n   model].\n\n[`Mutex`]: https://doc.rust-lang.org/std/sync/struct.Mutex.html\n[atomic]: https://doc.rust-lang.org/std/sync/atomic/index.html\n[actor model]: https://en.wikipedia.org/wiki/Actor_model\n\n\n## Getting started\n\nFirst, you'll need a recent nightly compiler. [rustup] is the easiest way\nto install and manage different rust installations. The following command will\ninstall a nightly compiler with rustup.\n\n```bash\nrustup install nightly # Install the latest nightly compiler.\n\n# Optional:\nrustup default nightly # Set the nightly compiler as default.\n```\n\nSecond, Heph needs to be added as a dependency. Most likely you'll also want the\nHeph runtime (`heph-rt`).\n\n```toml\n[dependencies]\nheph    = \"0.5.0\"\nheph-rt = \"0.5.0\"\n```\n\nNow, you're ready to starting writing your application! Next, you can look at\nsome [examples], look at the [API documentation] or get started with the [Quick\nStart Guide].\n\n[rustup]: https://rustup.rs\n[API documentation]: https://docs.rs/heph\n[Quick Start Guide]:  https://docs.rs/heph/latest/heph/quick_start/index.html\n\n\n## Platform support\n\n~~The main target platform is Linux, as a production target. We also support\nmacOS, but only as development target (e.g. develop on macOS and run Linux in\nproduction). Other BSDs are mostly supported (kqueue is fully supported),\nhowever no tests are run on these platforms.~~\n\nSince the switch to io\\_uring only Linux is supported. Best supported is Linux\nTLS versions, at the time of writing Linux v6.1. Support for other Unix targets\nsuch as macOS and the BSDs might return in the future.\n\n\n## Stability\n\nCurrently this project is *unstable*, since the crate depends on many\nexperimental or Nightly only Rust features. So, it can only be compiled using a\nNightly version of the Rust compiler. Furthermore, the crate itself is\n\u003c v1, meaning the API is far from stable as well. In fact, improvements to the\nAPI are very welcome!\n\n\n## License\n\nLicensed under the MIT license ([LICENSE] or\nhttps://opensource.org/licenses/MIT).\n\n[LICENSE]: ./LICENSE\n\n\n### Contribution\n\nUnless you explicitly state otherwise, any contribution intentionally submitted\nfor inclusion in the work by you shall be licensed as above, without any\nadditional terms or conditions.\n\n\n## Inspiration\n\nHeph is inspired by a number of other frameworks and languages. The greatest\ninspiration is the [Erlang] programming language. From Erlang, the concept of\nprocesses, or rather a function as a process, is borrowed. In line with the\nactor model, the processes (actors) cannot access each other's memory, instead\nmessage passing is used to communicate.\n\nAnother inspiration is the [Akka] framework for Scala and Java. Where Erlang is\na functional language, Akka is implemented in/for Scala and Java, languages more\nin line with Rust (both being object oriented, but having functional aspects). A\nlot of the API is inspired by the API provided in Akka, but there are a number\nof big differences. The main one being that Akka's actor are untyped (or at\nleast can be), where Heph actors are statically typed (just like Rust in\ngeneral).\n\nThe final inspiration I would like to mention is [Nginx]. Nginx is an HTTP and\nreverse proxy server. The architecture used in Nginx is running a single master\nprocess (not a thread) that coordinates a number of worker processes (again not\nthreads), each with their own polling instance (epoll/kqueue etc.) which all\nshare the same TCP listeners. In early stages of development of Heph, the idea\nwas to start a new process per CPU core (much like Nginx). This would allow all\natomic and locking operations to be dropped. However, this was later changed to\nstart threads instead to reduce the complexity when working with other\nlibraries. In the original design, it wouldn't be possible to work with any\nlibraries that started threads because we could introduce data races–something\nthat Rust tries very hard to avoid. Still, most of the architecture was\ninspired by the one used in Nginx.\n\n[Erlang]: https://www.erlang.org\n[Akka]: https://akka.io\n[Nginx]: https://nginx.org\n\n\n### Building blocks\n\nBesides the inspiration gained from the work of others, Heph is also built upon\nthe work of others. Three major components used in Heph are the futures task\nsystem (part of the standard library), asynchronous functions, and [A10].\n\n[A10]: https://github.com/Thomasdezeeuw/a10\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthomasdezeeuw%2Fheph","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthomasdezeeuw%2Fheph","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthomasdezeeuw%2Fheph/lists"}