Rust example improve suggestion

[wisonye]

Hi there, I just went through the first 2 examples for the Rust guide. Below is my personal opinion which may improve the user learning experience for a beginner like me. Free feel to take a look one by one:

• 01-node.rs

  use ockam::{Context, Result};
  
  /// If you want to know what source code the `#[ockam::node]` will generated for you,
  /// then you can run `cargo expand --example 01-node` and you should see the output like below:
  ///
  /// ```ignore
  /// #[inline(always)]
  /// async fn trampoline(mut ctx: Context) -> Result<()> {
  ///     ctx.stop().await;
  ///     Ok(())
  /// }
  /// fn main() -> ockam::Result<()> {
  ///     let (ctx, mut executor) = ockam::start_node();
  ///     executor.execute(async move {
  ///         trampoline(ctx).await.unwrap();
  ///     })
  /// }
  /// ```
  ///
  /// If you want to print the debug info for the `Context`, then go to the `Context` definition
  /// and add the `#[derive(Debug)]` like below:
  ///
  /// ```ignore
  /// #[derive(Debug)]
  /// pub struct Context {
  ///     address: AddressSet,
  ///     sender: Sender<NodeMessage>,
  ///     rt: Arc<Runtime>,
  ///     pub(crate) mailbox: Mailbox,
  /// }
  /// ```
  ///
  /// After that, run `cargo clean && cargo run --example 01-node`. Then you should be able to 
  /// see the entire `Context` instance debug info like below:
  ///
  /// ```ignore
  /// ctx: Context {
  ///     address: AddressSet(
  ///         [
  ///             0#app,
  ///         ],
  ///     ),
  ///     sender: Sender {
  ///         chan: Tx {
  ///             inner: Chan {
  ///                 tx: Tx {
  ///                     block_tail: 0x00007fa88081d600,
  ///                     tail_position: 0,
  ///                 },
  ///                 semaphore: (
  ///                     Semaphore {
  ///                         permits: 32,
  ///                     },
  ///                     32,
  ///                 ),
  ///                 rx_waker: AtomicWaker,
  ///                 tx_count: 2,
  ///                 rx_fields: "...",
  ///             },
  ///         },
  ///     },
  ///     rt: Runtime {
  ///         kind: ThreadPool(
  ///             ThreadPool,
  ///         ),
  ///         handle: Handle {
  ///             spawner: ThreadPool(
  ///                 Spawner,
  ///             ),
  ///             io_handle: Some(
  ///                 Handle,
  ///             ),
  ///             signal_handle: Some(
  ///                 Handle {
  ///                     inner: (Weak),
  ///                 },
  ///             ),
  ///             time_handle: Some(
  ///                 Handle,
  ///             ),
  ///             clock: Clock,
  ///             blocking_spawner: blocking::Spawner,
  ///         },
  ///         blocking_pool: BlockingPool,
  ///     },
  ///     mailbox: Mailbox {
  ///         rx: Receiver {
  ///             chan: Rx {
  ///                 inner: Chan {
  ///                     tx: Tx {
  ///                         block_tail: 0x00007fa88081de00,
  ///                         tail_position: 0,
  ///                     },
  ///                     semaphore: (
  ///                         Semaphore {
  ///                             permits: 32,
  ///                         },
  ///                         32,
  ///                     ),
  ///                     rx_waker: AtomicWaker,
  ///                     tx_count: 2,
  ///                     rx_fields: "...",
  ///                 },
  ///             },
  ///         },
  ///         tx: Sender {
  ///             chan: Tx {
  ///                 inner: Chan {
  ///                     tx: Tx {
  ///                         block_tail: 0x00007fa88081de00,
  ///                         tail_position: 0,
  ///                     },
  ///                     semaphore: (
  ///                         Semaphore {
  ///                             permits: 32,
  ///                         },
  ///                         32,
  ///                     ),
  ///                     rx_waker: AtomicWaker,
  ///                     tx_count: 2,
  ///                     rx_fields: "...",
  ///                 },
  ///             },
  ///         },
  ///     },
  /// }
  /// ```
  #[ockam::node]
  async fn main(mut ctx: Context) -> Result<()> {
      // Uncomment this line if you want to take a look at the `Context`
      // debug info which can help you know more about it.
      // println!("ctx: {:#?}", &ctx);
  
      ctx.stop().await
  }

  I think that it's important for the user to know about How #[ockam::node] works. So the cargo expand comment is super useful, it gives a very clear view to the user to know what happens under the hood. Here is the output:

  

  For the #[derive(Debug)] comment, it looks a bit longer for the example which should focus on "clean and simple", but the output is very valuable. Or maybe place or mentioned it into the plain text outside the example source code?:)

---

• echoer

  use ockam::{Context, Result, Routed, Worker};
  pub struct Echoer;
  
  #[ockam::async_worker]
  impl Worker for Echoer {
      type Context = Context;
      type Message = String;
  
      async fn handle_message(
          &mut self,
          ctx: &mut Self::Context,
          msg: Routed<Self::Message>,
      ) -> Result<()> {
          println!(
              "[ Worker address: {} ] - received msg: {}",
              ctx.address(),
              msg
          );
  
          // Echo the message body back on its return_route
          ctx.send(
              msg.return_route(),
              format!("<echo back message> {}", &msg.body()),
          )
          .await
      }
  }

• 02-worker.rs

  // examples/02-worker.rs
  
  use ockam::{Context, Result};
  use ockam_get_started::Echoer;
  
  const TEST_WORKER_ADDRESS: &'static str = "Another side";
  
  /// When a new `Node` start and call this `async main` function, it turns
  /// that `async main` function into a `Worker` with the address of `app`.
  #[ockam::node]
  async fn main(mut ctx: Context) -> Result<()> {
      // For testing the `Echoer` worker, we need to start a new `Worker`
      // with a different address which can be any string you wanted.
      let _ = ctx.start_worker(TEST_WORKER_ADDRESS, Echoer).await?;
  
      // Send a message from `app` address (Echoer) worker to the started (Echoer)
      // worker.
      let _ = ctx
          .send(TEST_WORKER_ADDRESS, "Hello, new workd:)".to_string())
          .await?;
  
      // It should print out
      // ```ignore
      // [ Worker address: 0#Another side ] - received msg: Hello, new worker:)
      // ```
  
      // Wait to receive the echo response
      let reply = ctx.receive::<String>().await?;
      println!("[ Worker address: app ] - received msg: {}", reply);
  
      // It should print out
      // ```ignore
      // [ Worker address: app ] - received msg: <echo back message> Hello, new worker:)
      // ```
  
      ctx.stop().await
  }

  After customizing the output format, cargo run --example 02-worker output content looks better than before:

  

I just report that from a beginner user's angle and I think this small detail change will give a better feeling and understanding for the first Ockam try:)

[mrinalwadhwa]

Hi @wisonye thank you for trying the examples!
Those are nice suggestions. I'll think about how to incorporate them into the guide over the next few days.

Please keep sending feedback as you try more examples. 🙏

[wisonye]

Love to do that:)

[wisonye]

Also, in the src/echoer.rs example, official code like this:

ctx.send(msg.return_route(), msg.body()).await

But I think you better put the comment there to let the developer knows that the .body(&self) will consume the entire msg itself. Otherwise, I think many developers will end up with the situation below which it's quite confusing:

As usually, .body() should be considered as just getting back the &Message or Option<Message>. no much developer will be considered as consuming the Message (I think).

[mrinalwadhwa]

Great point .body() used to be called .take() .. maybe that was a better name cc: @spacekookie @jared-s