bastion-rs / bastion

Highly-available Distributed Fault-tolerant Runtime
https://www.bastion-rs.com
Apache License 2.0
2.78k stars 101 forks source link

Perhaps provide some more gradual examples on the https://bastion.rs/ site? #334

Open werner291 opened 3 years ago

werner291 commented 3 years ago

Hello!

I've looked at https://bastion.rs/, and I must say that, as a newcomer, I find the examples a bit intimidating.

I have a basic understanding of how actors work, but when I look at the site, as a newcomer, what I see:

use bastion::prelude::*;

#[fort::root]
async fn main(_: BastionContext) -> Result<(), ()> {
    println!("Running in Bastion runtime!");
    Ok(())
}

My reaction: "Ok... I can print things inside of a 'runtime', whatever that is... Looks simple enough."

And then:

use bastion::prelude::*;
use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::Arc;

fn main() {
    Bastion::init();

    let started = AtomicBool::new(false);
    let started = Arc::new(started);

    Bastion::children(|children| {
        children.with_exec(move |ctx: BastionContext| {
            let started = started.clone();
            async move {
                println!("Started!");

                if started.swap(true, Ordering::SeqCst) {
                    println!("Already started once. Stopping...");

                    // This will ask the system to stop itself...
                    Bastion::stop();
                    // ...and this will stop this child immediately...
                    return Ok(());
                    // Note that if Err(()) was returned, the child would have been
                    // restarted (and if the system wasn't stopping).
                }

                // This will return None.
                let try_recv = ctx.try_recv().await;
// Lots more lines with supervisors, children, child groups, etc...

Bastion certainly looks interesting, and I'd love to learn more about it, but... Wow, that's a lot going on. What's the difference between a supervisor? A child group? A child? How does Fort come into that? What's a context? A runtime? Help!

As a basic example, it's a bit intimidating, there's kinda way too many concepts being introduced at once. It's probably going to scare away some beginners.

o0Ignition0o commented 3 years ago

Hey and thanks a lot for your feedback! It does indeed look quite overwhelming, we might need to refer to the examples instead!

We are currently trying to work on a bastion mdbook, that will hopefully ease folks into how it works, and maybe help us refactor the public APIs so they’re more convenient to use