1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107
//! This library allows you to build Rust applications that run on top of [Lunatic][1]. //! //! [**Join our growing community on Discord!**](https://!discord.gg/b7zDqpXpB4) //! //! ### Why would you want to run on top of Lunatic? //! //! Lunatic provides an [Erlang][2] like runtime for all programming languages that compile to [WebAssembly][3]. //! It's all about spawning _super lightweight_ processes, also known as green threads or [go-routines][5] in other //! runtimes. Lunatic processes are fast to create, have a small memory footprint and a low scheduling //! overhead. They are designed for **MASSIVE** concurrency. //! //! Lunatic processes are completely isolated from each other, they have their own stack, heap and even syscalls. If one //! process fails it will not affect the rest of the system. This allows you to create very powerful and fault-tolerant //! abstraction. //! //! All processes running on Lunatic are preemptively scheduled and executed by a [work stealing async executor][6]. This //! gives you the freedom to write simple _blocking_ code, but the runtime is going to make sure it actually never blocks //! a thread if waiting on I/O. //! //! To learn more about Lunatic's architecture check out the [runtime repository][1]. It's written in Rust :) //! //! ### Example //! //! This example application spawns a process and waits for it to print a message on the screen. //! //! ```rust //! use lunatic::Process; //! //! fn main() { //! Process::spawn((), |_: ()| { //! println!("Hello from inside the new process!"); //! }) //! .unwrap() //! .join(); //! } //! ``` //! //! Check out more examples [here](https://github.com/lunatic-solutions/rust-lib/tree/main/examples). //! //! ### Requirements //! //! To run the example you will first need to download the Lunatic runtime by following the installation steps in //! [this repository][1]. //! //! [Lunatic][1] applications need to be compiled to [WebAssembly][3] before they can be executed by the runtime. //! Rust has great support for WebAssembly and you can build a Lunatic compatible application just by passing the //! `--target=wasm32-wasi` flag to cargo, e.g: //! //! ``` //! cargo build --release --target=wasm32-wasi //! ``` //! //! This will generate a .wasm file in the `target/wasm32-wasi/release/` folder inside your project. //! You can now run your application by passing the generated .wasm file to Lunatic, e.g: //! //! ``` //! lunatic target/wasm32-wasi/release/<name>.wasm //! ``` //! //! ### Supported Features //! //! Some features are directly supported through Rust's standard library, like filesystem access (`std::fs::File`). //! Others are specific to Lunatic, like process spawning (`lunatic::Process`). //! //! Some features that are usually available in Rust's standard library (like TCP, e.g. `std::net::TcpListener`) are //! not standardised yet by [WASI][4]. So we made them available through **this library** (e.g. `lunatic::net::TcpListener`). //! Once WASI gets support for this features you will be able to just use the standard library versions. //! //! What currently works: //! //! - `[x]` **Process creation & joining** (with this library) //! - `[ ]` **Fine-grained process permissions** (with this library) //! - `[x]` **Channel based message passing** (with this library) //! - `[x]` **TCP networking** (with this library) //! - `[ ]` **Filesystem access** //! - `[x]` **Environment variables** //! - `[ ]` **Multithreading** //! //! > **NOTE:** //! > Some libraries currently don't compile under the target `wasm32-wasi` and can't be used inside Lunatic applications. //! //! [1]: https://!github.com/lunatic-solutions/lunatic //! [2]: https://!www.erlang.org/ //! [3]: https://!webassembly.org/ //! [4]: https://!wasi.dev/ //! [5]: https://!golangbot.com/goroutines //! [6]: https://!docs.rs/smol pub mod channel; pub mod net; pub mod process; pub use process::Process; mod stdlib { #[link(wasm_import_module = "lunatic")] extern "C" { pub fn yield_(); } } /// Yields current process. pub fn yield_() { unsafe { stdlib::yield_(); } }