Merge pull request #23 from togglebyte/dev

async recipe and document hot reloading

Author: togglebyte

src/recipes.md

@@ -1,18 +1,8 @@
 # Recipes
 
-* Themeing
-* Async
-* [Routing](./recipes/routing.md)
+Various recipes for solving certain common scenarios.
 
-```rust,ignore
-#[derive(State)]
-struct MyState {
-    value: Value<bool>,
-}
-```
+* [Routing](./recipes/routing.md)
+* [Async](./recipes/async.md)
+* Themes
 
-```aml
-border
-    vstack
-        text "Hello world"
-```

src/recipes/async.md

@@ -0,0 +1,63 @@
+# Async and Anathema
+
+Since the UI `Runtime` is blocking, spawn a secondary thread for our async
+runtime to run on.
+
+The `Runtime` can not move between threads as the `Value`s are not send.
+That's why it's easier, if access to component ids and emitters are required, to
+run the async code on a separate thread from the main thread.
+
+## Setting up for async
+
+A function that starts an async runtime in a new thread.
+
+By accepting a component id and an emitter it is possible to send messages into
+the Anathema runtime.
+
+```rust,ignore
+pub fn run_async(emitter: Emitter, component: ComponentId<MessageType>) {
+    thread::spawn(move || {
+        tokio::runtime::Builder::new_multi_thread()
+            .enable_all()
+            .build()
+            .unwrap()
+            .block_on(async move {
+                // async code here
+            });
+    });
+}
+```
+
+## Setup the UI
+
+Setup the Anathema runtime on the main thread,
+generate component ids and emitters and pass them to the async runtime via the
+aforementioned function.
+
+```rust,ignore
+use anathema::component::*;
+use anathema::prelude::*;
+
+fn main() {
+    // -----------------------------------------------------------------------------
+    //   - Setup UI -
+    // -----------------------------------------------------------------------------
+    let doc = Document::new("@index");
+
+    let mut backend = TuiBackend::full_screen();
+    let mut builder = Runtime::builder(doc, &backend);
+    
+    let component_id = builder.default::<MyComponent>("index", "templates/index.aml").unwrap();
+    let emitter = builder.emitter();
+
+    // -----------------------------------------------------------------------------
+    //   - Setup async -
+    // -----------------------------------------------------------------------------
+    run_async(emitter, component_id);
+
+    // -----------------------------------------------------------------------------
+    //   - Start UI -
+    // -----------------------------------------------------------------------------
+    builder.finish(&mut backend, |runtime, backend| runtime.run(backend)).unwrap();
+}
+```

src/runtime.md

@@ -73,6 +73,18 @@ Hot reloading won't work on components that store internal state either, such as
 the `Canvas` widget.
 </div>
 
+To disable hot reloading:
+
+```rust,ignore
+runtime.hot_reload(false);
+```
+
+To enable hot reloading:
+
+```rust,ignore
+runtime.hot_reload(true);
+```
+
 ### Multiple instances of a component
 
 To repeatedly use a component in a template, e.g: