mirror of https://github.com/poanetwork/hbbft.git
Include advice on how to handle `Step` in docs. (#297)
* Fixed spelling mistake in `Step` docs. * Added suggestion on how to handle `Step` output.
This commit is contained in:
parent
df36258715
commit
5f21c9a4e4
|
@ -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<C> Contribution for C where C: Eq + Debug + Hash + Send + Sync {}
|
||||
|
||||
|
@ -26,8 +26,28 @@ impl<M> Message for M where M: Debug + Send + Sync {}
|
|||
pub trait SessionIdT: Display + Serialize + Send + Sync + Clone {}
|
||||
impl<S> 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<D>
|
||||
|
@ -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()
|
||||
}
|
||||
|
|
Loading…
Reference in New Issue