Expand description

Framework for building Rust applications that run on lunatic.

Main concepts

The main abstraction in lunatic is a process. Contrary to operating system processes, lunatic processes are lightweight and fast to spawn. They are designed for massive concurrency. Like operating system processes, they are sandboxed. Each of them gets a separate memory and they can’t access the memory from other processes, not even through raw pointers. If we want to exchange any information between process we need to do it through message passing.

This library makes processes feel native to the Rust language. They can be spawned from just a function.

Process types:

Linking

Processes can be linked together. This means that if one of them fails, all linked ones will be killed too.

To spawn a linked process use the spawn_link function.

Process configuration

Spawn functions have a variant that takes a ProcessConfig. This configuration can be used to set a memory or CPU limit on the newly spawned process. It can also be used to control file and network access permissions of processes.

Setup

To run the example you will first need to download the lunatic runtime by following the installation steps in this repository. The runtime is just single executable and runs on Windows, macOS and Linux. If you have already Rust installed, you can get it with:

cargo install lunatic-runtime

Lunatic applications need to be compiled to WebAssembly 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:

rustup target add wasm32-wasi
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
Better developer experience

To simplify developing, testing and running lunatic applications with cargo, you can add a .cargo/config.toml file to your project with the following content:

[build]
target = "wasm32-wasi"

[target.wasm32-wasi]
runner = "lunatic"

Now you can just use the commands you were already familiar with, such as cargo run, cargo test and cargo is going to automatically build your project as a WebAssembly module and run it inside lunatic.

Testing

Lunatic provides a macro test to turn your tests into processes. Check out the tests directory for examples.

Modules

Low level lunatic VM syscalls.

Networking related functions.

Serializer implementations for messages.

Macros

Declare a new process local storage of type ProcessLocal.

Helper macro for spawning processes.

Helper macro for spawning linked processes.

Structs

Mailbox of a Process.

Processes are isolated units of compute.

Process configurations determine permissions of processes.

A process local storage which owns its contents.

A i64 value used as a message tag.

Enums

An opaque error returned from host calls.

Error while receiving a message.

A compiled instance of a WebAssembly module.

Traits

Implemented for all resources held by the VM.

Functions

Suspends the current process for duration of time.

Attribute Macros

Add AbstractProcess behavior to the given struct implementation with minimum boilerplate code.

Marks the main function to be executed by the lunatic runtime as the root process.

Marks function to be executed by the lunatic runtime as a unit test. This is a drop-in replacement for the standard #[test] attribute macro.