Crate lunatic

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:

• Process - A process that can receive messages through a Mailbox or Protocol.
• AbstractProcess - Abstracts state management and message/request handling.
• Supervisor - A process that can supervise others and re-spawn them if they fail.

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:

# Add the WebAssembly target
rustup target add wasm32-wasi
# Build the app
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 run 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 run"

or inside of your Cargo project just run:

lunatic init

This will automatically crate the file above.

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 test macro to run your tests inside processes. Check out the tests directory for examples.

Re-exports

• pub use ap::AbstractProcess;

Modules

• ap
  Contains the AbstractProcess abstraction.
• distributed
• function
• host
  Low level lunatic VM syscalls.
• metrics
  Expose metrics functions from lunatic’s runtime Lunatic’s runtime comes with metrics integration and can expose those metrics to prometheus if prometheus feature is enable at build time and using –prometheus flag to start the exporter
• net
  Networking related functions.
• panic
• protocol
• serializer
  Serializer implementations for messages.
• sqlitesqlite
  Sqlite database client.
• supervisor
• time
  Contains helper structures to deal with time-related functionality.

Macros

• process_local
  Declare a new process local storage of type ProcessLocal.
• spawn
  Helper macro for spawning processes.
• spawn_link
  Helper macro for spawning linked processes.

Structs

• LinkDiedSignal
  A linked process died.
• Mailbox
  The mailbox of a Process.
• MessageSignalConvertError
  Error returned when converting a MessageSignal.
• Process
  Processes are isolated units of compute.
• ProcessConfig
  Process configurations determine permissions of processes.
• ProcessDiedSignal
  A monitored process died.
• ProcessLocal
  A process local storage which owns its contents.
• Tag
  A i64 value used as a message tag.

Enums

• LunaticError
  An opaque error returned from host calls.
• MailboxError
  An error returned when receiving from a mailbox.
• MessageSignal
  Result of a recieve* call on a Mailbox.
• Param
• Signal
  A signal received when a link dies or monitored process dies.
• WasmModule
  A compiled instance of a WebAssembly module.

Traits

• ProcessName
  ProcessName is used to uniquely name a process from a Rust type.
• Resource
  Implemented for all resources held by the VM.

Functions

• lunatic_alloc
• sleep
  Suspends the current process for duration of time.

Type Definitions

• MailboxResult

Attribute Macros

• abstract_process
  Add AbstractProcess behavior to the given struct implementation with minimum boilerplate code.
• main
  Marks the main function to be executed by the lunatic runtime as the root process.
• test
  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.

Derive Macros

• ProcessName
  ProcessName implements the lunatic::ProcessName trait by generating a unique name in the following format: