Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve getting started experience #238

Open
lulf opened this issue Mar 16, 2022 · 4 comments
Open

Improve getting started experience #238

lulf opened this issue Mar 16, 2022 · 4 comments

Comments

@lulf
Copy link
Member

lulf commented Mar 16, 2022

Current issues where we can improve

  • Taking the step from example to standalone crate (templates)
  • Simpler more understandable examples for basic things like blinky
  • Better example documentation both in code and readme (now included inline in book as of Improve docs navigation #237)

@ctron Iirc, you had some more points around actor documentation. Could you add those points here? There are some actor introcution in the 'Introduction', and a programmatic introduction in the 'Basic application' section of https://book.drogue.io/drogue-device/dev/index.html. But iirc you had some other valid points.

@ctron
Copy link
Member

ctron commented Mar 17, 2022

What I guess would help is:

  • Add some documentation on the actor model of Drogue Device
    • What is an actor
    • What is the lifecycle? Init, Inbox, ...
    • When to use an actor vs when not to
  • A basic tutorial, which builds (step by step) a simple device (like a blinking LED with a push-button that changes its behavior). Maybe pointing to a dedicated GitHub repository, which contains the full code (and only that). Ready to check out, build, and flash on a device we choose (like the microbit).

@ctron
Copy link
Member

ctron commented Mar 17, 2022

Ok, after re-checking the docs. I think it already is there.

@lulf
Copy link
Member Author

lulf commented Mar 21, 2022

Improvements:

Will take a stab at improving the code docs.

@lulf
Copy link
Member Author

lulf commented Mar 23, 2022

I'm going to attempt to improve the experience of writing and running actors as follows:

  1. Introduce a spawn_actor! macro to simplify creation and mounting of the actor context + actor:
let address = spawn_actor!(spawner, BUTTON_A, Button::new(board.btn_a));
  1. Introduce a actor proc macro to simplify the Actor impl:
#[actor]
impl Actor for MyActor {
    type Message<'m> = MyMessage;
    async fn on_mount<M>(&mut self, address: Address<Self>, inbox: &mut M)
        where M: Inbox<Self>
    {
        loop {
            if let Some(m) = inbox.next().await {
                // ... handle message
            }
        }
    }
}

The purpose of this macro is not to remove all the boilerplate, but rather prepare the actor implementations to require minimal modifications when async traits are fully available in Rust, so that just removing the #[actor] macro (and making the macro a dummy) will allow the code to keep working.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants