Merge pull request #687 from swimos/devguide

New developer guide structure

Author: SirCipher

Cargo.toml

@@ -40,8 +40,7 @@ members = [
     "example_apps/join_value",
     "example_apps/aggregations",
     "example_apps/time_series",
-    "example_apps/devguide/2_2/*",
-    "example_apps/devguide/2_3/*",
+    "example_apps/devguide",
 ]
 
 [workspace.package]
@@ -173,4 +172,4 @@ waker-fn = "1.1.0"
 num = "0.4"
 smol_str = "0.2.0"
 http-body-util = "0.1.2"
-hyper-util = "0.1.5"
+hyper-util = "0.1.5"

example_apps/devguide/2_2/example_client/Cargo.toml

@@ -0,0 +1,17 @@
+[package]
+name = "devguide2"
+version.workspace = true
+authors.workspace = true
+edition.workspace = true
+license.workspace = true
+homepage.workspace = true
+publish = false
+
+[dependencies]
+swimos = { workspace = true, features = ["server", "agent"] }
+swimos_client = { workspace = true }
+swimos_form = { workspace = true }
+tokio = { workspace = true, features = ["rt-multi-thread", "macros"] }
+
+[[bin]]
+name = "devguide_client"

example_apps/devguide/2_2/example_client/src/main.rs

@@ -1,4 +1,5 @@
-use swimos_client::{BasicValueDownlinkLifecycle, DownlinkConfig, RemotePath, SwimClientBuilder};
+use std::error::Error;
+use swimos_client::{BasicValueDownlinkLifecycle, RemotePath, SwimClientBuilder};
 use swimos_form::Form;
 
 #[derive(Debug, Form, Copy, Clone)]
@@ -8,12 +9,12 @@ pub enum Operation {
 }
 
 #[tokio::main]
-async fn main() {
+async fn main() -> Result<(), Box<dyn Error>> {
     // Build a Swim Client using the default configuration.
     // The `build` method returns a `SwimClient` instance and its internal
     // runtime future that is spawned below.
     let (client, task) = SwimClientBuilder::default().build().await;
-    let _client_task = tokio::spawn(task);
+    let client_task = tokio::spawn(task);
     let handle = client.handle();
 
     // Build a path the downlink.
@@ -28,24 +29,14 @@ async fn main() {
     );
 
     let lifecycle = BasicValueDownlinkLifecycle::<usize>::default()
-        // Register an event handler that is invoked when the downlink connects to the agent.
-        .on_linked_blocking(|| println!("Downlink linked"))
-        // Register an event handler that is invoked when the downlink synchronises its state.
-        // with the agent.
-        .on_synced_blocking(|value| println!("Downlink synced with: {value:?}"))
         // Register an event handler that is invoked when the downlink receives an event.
         .on_event_blocking(|value| println!("Downlink event: {value:?}"));
 
-    // Build our downlink.
-    //
-    // This operation may fail if there is a connection issue.
-    let _state_downlink = handle
+    handle
         .value_downlink::<usize>(state_path)
         .lifecycle(lifecycle)
-        .downlink_config(DownlinkConfig::default())
         .open()
-        .await
-        .expect("Failed to open downlink");
+        .await?;
 
     let exec_path = RemotePath::new(
         // The host address
@@ -57,17 +48,11 @@ async fn main() {
         "exec",
     );
 
-    let exec_downlink = handle
-        .value_downlink::<Operation>(exec_path)
-        .downlink_config(DownlinkConfig::default())
-        .open()
-        .await
-        .expect("Failed to open exec downlink");
+    let exec_downlink = handle.value_downlink::<Operation>(exec_path).open().await?;
 
-    exec_downlink.set(Operation::Add(1000)).await.unwrap();
-    exec_downlink.set(Operation::Sub(13)).await.unwrap();
+    exec_downlink.set(Operation::Add(1000)).await?;
+    exec_downlink.set(Operation::Sub(13)).await?;
 
-    tokio::signal::ctrl_c()
-        .await
-        .expect("Failed to listen for ctrl-c.");
+    client_task.await?;
+    Ok(())
 }

example_apps/devguide/2_2/example_server/Cargo.toml

@@ -1,15 +1,15 @@
+use std::{error::Error, time::Duration};
+
+use swimos::agent::event_handler::HandlerActionExt;
+use swimos::agent::lanes::CommandLane;
 use swimos::{
     agent::{
         agent_lifecycle::HandlerContext, agent_model::AgentModel, event_handler::EventHandler,
         lanes::ValueLane, lifecycle, projections, AgentLaneModel,
     },
     route::RoutePattern,
-    server::{Server, ServerBuilder, ServerHandle},
+    server::{Server, ServerBuilder},
 };
-
-use std::{error::Error, time::Duration};
-use swimos::agent::event_handler::HandlerActionExt;
-use swimos::agent::lanes::CommandLane;
 use swimos_form::Form;
 
 // Note how as this is a custom type we need to derive `Form` for it.
@@ -115,24 +115,8 @@ async fn main() -> Result<(), Box<dyn Error + Send + Sync>> {
 
     // Run the server. A tuple of the server's runtime
     // future and a handle to the runtime is returned.
-    let (task, handle) = server.run();
-    // Watch for ctrl+c signals
-    let shutdown = manage_handle(handle);
-
-    // Join on the server and ctrl+c futures.
-    let (_, result) = tokio::join!(shutdown, task);
+    let (task, _handle) = server.run();
+    task.await?;
 
-    result?;
-    println!("Server stopped successfully.");
     Ok(())
 }
-
-// Utility function for awaiting a stop signal in the terminal.
-async fn manage_handle(mut handle: ServerHandle) {
-    tokio::signal::ctrl_c()
-        .await
-        .expect("Failed to register interrupt handler.");
-
-    println!("Stopping server.");
-    handle.stop();
-}