From 5f21c9a4e49acc9a95e72ba13ef1f594030c8f24 Mon Sep 17 00:00:00 2001 From: Marc Brinkmann Date: Tue, 30 Oct 2018 11:31:50 +0100 Subject: [PATCH] Include advice on how to handle `Step` in docs. (#297) * Fixed spelling mistake in `Step` docs. * Added suggestion on how to handle `Step` output. --- src/traits.rs | 28 ++++++++++++++++++++++++---- 1 file changed, 24 insertions(+), 4 deletions(-) diff --git a/src/traits.rs b/src/traits.rs index d659bc7f..56bffe42 100644 --- a/src/traits.rs +++ b/src/traits.rs @@ -10,7 +10,7 @@ use serde::Serialize; use fault_log::{Fault, FaultLog}; use TargetedMessage; -/// A transaction, user message, etc. +/// A transaction, user message, or other user data. pub trait Contribution: Eq + Debug + Hash + Send + Sync {} impl Contribution for C where C: Eq + Debug + Hash + Send + Sync {} @@ -26,8 +26,28 @@ impl Message for M where M: Debug + Send + Sync {} pub trait SessionIdT: Display + Serialize + Send + Sync + Clone {} impl SessionIdT for S where S: Display + Serialize + Send + Sync + Clone {} -/// Result of one step of the local state machine of a distributed algorithm. Such a result should -/// be used and never discarded by the client of the algorithm. +/// Single algorithm step outcome. +/// +/// Each time input (typically in the form of user input or incoming network messages) is provided +/// to an instance of an algorithm, a `Step` is produced, potentially containing output values, +/// a fault log, and network messages. +/// +/// Any `Step` **must always be used** by the client application; at the very least the resulting +/// messages must be queued. +/// +/// ## Handling unused Steps +/// +/// In the (rare) case of a `Step` not being of any interest at all, instead of discarding it +/// through `let _ = ...` or similar constructs, the implicit assumption should explicitly be +/// checked instead: +/// +/// ```ignore +/// assert!(alg.propose(123).expect("Could not propose value").is_empty(), +/// "Algorithm will never output anything on first proposal"); +/// ``` +/// +/// If an edge case occurs and outgoing messages are generated as a result, the `assert!` will +/// catch it, instead of potentially stalling the algorithm. #[must_use = "The algorithm step result must be used."] #[derive(Debug)] pub struct Step @@ -130,7 +150,7 @@ where } } - /// Returns `true` if there are now messages, faults or outputs. + /// Returns `true` if there are no messages, faults or outputs. pub fn is_empty(&self) -> bool { self.output.is_empty() && self.fault_log.is_empty() && self.messages.is_empty() }