Add readme file and some documentation to stdlib

stdlib/Readme.md

@@ -0,0 +1,47 @@
+# Rust bindings for Lunatic's stdlib
+
+This library contains higher level wrappers for low level Lunatic syscalls.
+
+Currently it requires nightly.
+
+### Example
+
+Create 100k processes and calculate the power of numbers then send the results back to the original process.
+
+```rust
+use lunatic::{Channel, Process};
+
+fn main() {
+    let channel = Channel::new(0);
+
+    for i in 0..100_000 {
+        let x = channel.clone();
+        Process::spawn(move || {
+            x.send((i, power(i)));
+        })
+        .unwrap();
+    }
+
+    for _ in 0..100_000 {
+        let (i, power) = channel.receive();
+        println!("Power of {} is {}", i, power);
+    }
+}
+
+fn power(a: i32) -> i32 {
+    a * a
+}
+
+```
+
+Compile your app with:
+
+```
+cargo build --release --target=wasm32-wasi
+```
+
+and run it with
+
+```
+lunatic target/wasm32-wasi/release/<name>.wasm
+```

stdlib/src/channel.rs

@@ -21,6 +21,8 @@ mod stdlib {
     }
 }
 
+/// A channel allows for sending messages between processes.
+/// The message is copied from one process to another, as processes don't share any memory.
 pub struct Channel<T> {
     id: u32,
     phantom: PhantomData<T>,

stdlib/src/lib.rs

@@ -1,5 +1,51 @@
 #![feature(optin_builtin_traits, negative_impls)]
 
+//! This library contains higher level wrappers for low level Lunatic syscalls.
+//!
+//! Currently it requires nightly.
+//!
+//! ### Example
+//!
+//! Create 100k processes and calculate the power of numbers then send the results back to the original process.
+//!
+//! ```rust
+//! use lunatic::{Channel, Process};
+//!
+//! fn main() {
+//!     let channel = Channel::new(0);
+//!
+//!     for i in 0..100_000 {
+//!         let x = channel.clone();
+//!         Process::spawn(move || {
+//!             x.send((i, power(i)));
+//!         })
+//!         .unwrap();
+//!     }
+//!
+//!     for _ in 0..100_000 {
+//!         let (i, power) = channel.receive();
+//!         println!("Power of {} is {}", i, power);
+//!     }
+//! }
+//!
+//! fn power(a: i32) -> i32 {
+//!     a * a
+//! }
+//!
+//! ```
+//!
+//! Compile your app to a WebAssembly target:
+//!
+//! ```
+//! cargo build --release --target=wasm32-wasi
+//! ```
+//!
+//! and run it with
+//!
+//! ```
+//! lunatic target/wasm32-wasi/release/<name>.wasm
+//! ```
+
 pub mod channel;
 pub mod process;
 
@@ -21,8 +67,8 @@ pub fn yield_() {
     }
 }
 
-/// Sending data to another process requires copying it into an independent buffer adn then reading
-///
+/// Sending data to another process requires copying it into an independent buffer.
+/// It's only safe to do so with copy types without serialisation.
 pub unsafe auto trait ProcessClosureSend {}
 
 impl<T> !ProcessClosureSend for &T where T: ?Sized {}

stdlib/src/process.rs

@@ -15,6 +15,8 @@ mod stdlib {
 #[derive(Debug)]
 pub struct SpawnError {}
 
+/// A process consists of its own stack and heap. It can only share data with other processes by
+/// sending it to them.
 pub struct Process {
     id: u32,
 }
@@ -29,6 +31,7 @@ impl Drop for Process {
 }
 
 impl Process {
+    /// Spawn a new process. The passed closure can only capture copy types.
     pub fn spawn<F>(closure: F) -> Result<Process, SpawnError>
     where
         F: FnOnce() + ProcessClosureSend,
@@ -71,6 +74,7 @@ impl Process {
         Ok(Self { id })
     }
 
+    /// Wait on a process to finish.
     pub fn join(self) {
         unsafe {
             stdlib::join(self.id);