An example application

A walkthrough of a basic Hadean Platform application

The SDK includes full API documentation for the Hadean Platform Rust crate. The latest version is available online and you can access it with Cargo by running:cargo doc --open from ~/.hadean/sdk/crates/hadean

#![feature(never_type)]
#![feature(raw)]

use futures::prelude::*;
use tokio::runtime::Runtime;

use ::hadean::channel::{Receiver, Sender};
use ::hadean::hadean;

/// This function is going to run in a separate process
/// when it is spawned by `parent`.
///
/// We accept a connection from the parent, and communicate with it.
fn child() {
    println!("child start");

    // We don't support spawning async functions yet.
    // For now, use tokio Runtime to block on an async closure.
    Runtime::new().unwrap().block_on(async move {
        // Accept communication from the parent process through a channel.
        let (sender, receiver) = hadean::accept().await.unwrap();
        let (mut sender, mut receiver): (Sender<String>, Receiver<String>) =
            (sender.into(), receiver.into());

        // Send a message to the parent from the child process.
        sender.send(String::from("child")).await.unwrap();

        // Receive a message from the parent process.
        let message = receiver.next().await.unwrap().unwrap();
        println!("child received: {}", message);
    });

    println!("child end");
}

/// This function is going to run in the initial process
/// when it is called from `main`.
///
/// Here, we are going to spawn `child` and communicate with it.
fn parent() {
    println!("parent start");

    // We don't support calling `Runtime::block_on` from within main,
    // nor do we support async main. So, we must create an async runtime
    // within the parent function.
    Runtime::new().unwrap().block_on(async move {
        // Create the child process.
        // This might or might not be created on the same machine.
        // The Hadean platform will take care of resource, process,
        // and communication management.
        let pid = hadean::spawn(child).await.expect("failed to spawn");

        // Communication between Hadean processes is established
        // through a channel.
        let (sender, receiver) = hadean::connect(pid).await.unwrap();
        let (mut sender, mut receiver): (Sender<String>, Receiver<String>) =
            (sender.into(), receiver.into());

        // Send a message to the child from the parent process.
        sender.send(String::from("parent")).await.unwrap();

        // Receive a message from the child process.
        let message = receiver.next().await.unwrap().unwrap();
        println!("parent received: {}", message);
    });

    println!("parent end");
}

fn main() {
    println!("entry");

    // Initialize hadean platform - enabling our process management and communication.
    // This needs to be called before any other method in the platform can be used.
    // Applications that call `hadean::init` must be run through the hadean CLI.
    hadean::init();

    // In this example, we run a parent process which spawns a child process and
    // then communicates between the two.
    parent();
}

init()

Used to initialise the Hadean Platform.

The init function should ideally be the first function called inside the application. While it is technically possible to run some code before calling init, you cannot rely on any code being executed once the target function returns. Ensure that any object put on the stack prior to this point has been deallocated/destroyed. If setup/teardown is essential, consider using trampoline functions.

spawn()

The spawn() function is where you create the processes that you want the Hadean Platform to distribute and scale. The Hadean Platform will take care of resource allocation, process and communication management.

connect()

connect(), along with accept() is how you establish communication between processes on the Hadean Platform. connect() accepts the process ID of the process to communicate with.

accept()

Accept an incoming connection request from a process that has used connect() to communicate.