From 57375b00850e7d88bf45031f1788721061b4bf9d Mon Sep 17 00:00:00 2001
From: Denis Varlakov <denis@dfns.co>
Date: Tue, 3 Dec 2024 13:13:54 +0100
Subject: [PATCH] Add example in state machine docs

Signed-off-by: Denis Varlakov <denis@dfns.co>
---
 Cargo.lock                           |  7 +++++
 round-based/Cargo.toml               |  2 ++
 round-based/src/lib.rs               |  1 +
 round-based/src/state_machine/mod.rs | 40 +++++++++++++++++++++++++---
 4 files changed, 46 insertions(+), 4 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index 06c4627..014e8b6 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -17,6 +17,12 @@ version = "1.0.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f26201604c87b1e01bd3d98f8d5d9a8fcbb815e8cedb41ffccbeb4bf593a35fe"
 
+[[package]]
+name = "anyhow"
+version = "1.0.93"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4c95c10ba0b00a02636238b814946408b1322d5ac4760326e6fb8ec956d85775"
+
 [[package]]
 name = "autocfg"
 version = "1.2.0"
@@ -471,6 +477,7 @@ dependencies = [
 name = "round-based"
 version = "0.4.0"
 dependencies = [
+ "anyhow",
  "displaydoc",
  "futures",
  "futures-util",
diff --git a/round-based/Cargo.toml b/round-based/Cargo.toml
index 5abf394..0637bcc 100644
--- a/round-based/Cargo.toml
+++ b/round-based/Cargo.toml
@@ -37,6 +37,8 @@ hex = "0.4"
 rand = "0.8"
 rand_dev = "0.1"
 
+anyhow = "1"
+
 [features]
 default = ["std"]
 state-machine = []
diff --git a/round-based/src/lib.rs b/round-based/src/lib.rs
index a035069..d93ff63 100644
--- a/round-based/src/lib.rs
+++ b/round-based/src/lib.rs
@@ -61,6 +61,7 @@ pub use futures_util::{Sink, SinkExt, Stream, StreamExt};
 /// Fixes false-positive of `unused_crate_dependencies` lint that only occur in the tests
 #[cfg(test)]
 mod false_positives {
+    use anyhow as _;
     use futures as _;
     use trybuild as _;
 
diff --git a/round-based/src/state_machine/mod.rs b/round-based/src/state_machine/mod.rs
index 7b12c84..21fd370 100644
--- a/round-based/src/state_machine/mod.rs
+++ b/round-based/src/state_machine/mod.rs
@@ -7,9 +7,11 @@
 //!
 //! ## Example
 //! ```rust,no_run
+//! # #[tokio::main(flavor = "current_thread")]
+//! # async fn main() -> anyhow::Result<()> {
 //! use round_based::{Mpc, PartyIndex};
+//! use anyhow::{Result, Error, Context as _};
 //!
-//! # type Result<T, E = ()> = std::result::Result<T, E>;
 //! # type Randomness = [u8; 32];
 //! # type Msg = ();
 //! // Any MPC protocol
@@ -25,11 +27,41 @@
 //! # todo!()
 //! }
 //!
-//! let state_machine = round_based::state_machine::wrap_protocol(
+//! // `state` implements `round_based::state_machine::StateMachine` trait.
+//! // Its methods can be used to advance protocol until completion.
+//! let mut state = round_based::state_machine::wrap_protocol(
 //!     |party| protocol_of_random_generation(party, 0, 3)
 //! );
-//! // `state_machine` implements `round_based::state_machine::StateMachine` trait.
-//! // Its methods can be used to advance protocol until completion.
+//!
+//! // Note: this is just an example. If you have stream/sink, you don't probably need to
+//! // use the sync API
+//! use futures::{Sink, Stream, SinkExt, StreamExt};
+//! async fn connect() -> Result<(
+//!     impl Stream<Item = anyhow::Result<round_based::Incoming<Msg>>>,
+//!     impl Sink<round_based::Outgoing<Msg>, Error = Error>
+//! )> {
+//!     // ...
+//!     # Ok((futures_util::stream::pending(), futures_util::sink::drain().sink_map_err(|err| match err {})))
+//! }
+//! let (mut incomings, mut outgoings) = connect().await?;
+//!
+//! use round_based::state_machine::{StateMachine as _, ProceedResult};
+//! let output = loop {
+//!     match state.proceed() {
+//!         ProceedResult::SendMsg(msg) => {
+//!             outgoings.send(msg).await?
+//!         }
+//!         ProceedResult::NeedsOneMoreMessage => {
+//!             let msg = incomings.next().await.context("unexpected eof")??;
+//!             state.received_msg(msg)
+//!                 .map_err(|_| anyhow::format_err!("state machine rejected received message"))?;
+//!         }
+//!         ProceedResult::Yielded => {},
+//!         ProceedResult::Output(out) => break Ok(out),
+//!         ProceedResult::Error(err) => break Err(err),
+//!     }
+//! };
+//! # Ok(()) }
 //! ```
 
 mod delivery;