M src/list/raxos/protocal/src/apaxos/acceptor.rs

src/list/raxos/protocal/src/apaxos/acceptor.rs

@@ -4,8 +4,8 @@ use std::fmt::Debug;
 
 use validit::Validate;
 
+use crate::apaxos::branch::Branch;
 use crate::apaxos::decided::Decided;
-use crate::apaxos::focal_history::FocalHistory;
 use crate::apaxos::history::History;
 use crate::Types;
 
@@ -39,7 +39,7 @@ impl<T: Types> Acceptor<T> {
     pub(crate) fn handle_phase1_request(
         &mut self,
         commit_time: T::Time,
-    ) -> Result<FocalHistory<T>, T::Time> {
+    ) -> Result<Branch<T>, T::Time> {
         self.check_committable(&commit_time)?;
 
         self.forbid_smaller_commit_time(commit_time);

src/list/raxos/protocal/src/apaxos/branch.rs

@@ -0,0 +1,96 @@
+use crate::apaxos::decided::Decided;
+use crate::Types;
+
+// For doc reference
+#[rustfmt::skip]
+#[allow(unused_imports)]
+use crate::apaxos::{
+    history::History,
+    proposer::Proposer
+};
+
+/// Indicate the [`Branch`] includes an event has been set at the head
+/// time.
+pub const HEAD_SET: bool = true;
+
+/// Indicate the [`Branch`] **may** not include an event at the head
+/// time. Note that the head time is already in the internal history.
+pub const HEAD_UNSET: bool = false;
+
+pub type HeadEventState = bool;
+
+/// Represents a single branch [`History`] that is reachable upto a designated
+/// "head" time.
+///
+/// It represents a subset of the history that includes all time and events
+/// **before or equal** a specific "time".
+///
+/// Unlike a [`History`], which may contain multiple maximal times due to
+/// the partial ordering of events, [`Branch`] has a single, well-defined
+/// "head time" that serves as the focal point of this historical view.
+///
+/// This struct is used by a [`Proposer`] to represent the system state it
+/// observes at a given moment,
+/// with a clear notion of what it considers to be the head time.
+#[derive(Debug, Clone, Default)]
+pub struct Branch<T, const HEAD: HeadEventState>
+where T: Types
+{
+    head_time: T::Time,
+    history: T::History,
+}
+
+impl<T> Branch<T, HEAD_UNSET>
+where T: Types
+{
+    pub fn new(head_time: T::Time, history: T::History) -> Self {
+        Self { head_time, history }
+    }
+
+    /// Attempts to add an [`Event`] at the **head time**, and create a
+    /// [`Decided`] instance.
+    ///
+    /// The returned [`Decided`] instance include all events from this view,
+    /// plus the new event at the **head time**.
+    ///
+    /// This method should return an `Err` if there is already an [`Event`] at
+    /// the ([`Self::head_time()`]).
+    pub fn add_event(
+        mut self,
+        event: T::Event,
+    ) -> Result<Branch<T, HEAD_SET>, Branch<T, HEAD_SET>> {
+        if let Some(_ev) = self.history.get(&self.head_time) {
+            // Nothing to do
+        } else {
+            self.history.append(self.head_time, event).unwrap();
+        }
+
+        Ok(Branch::<T, HEAD_SET> {
+            head_time: self.head_time,
+            history: self.history,
+        })
+    }
+}
+
+impl<T, const HEAD: HeadEventState> Branch<T, HEAD>
+where T: Types
+{
+    /// Returns the head time of this branch.
+    ///
+    /// This time represents the **greatest** single time.
+    /// All events in the view are causally prior to or equal this time.
+    ///
+    /// The head time is the **now**, new event can only be added at **now**,
+    /// not at a time in the past.
+    ///
+    /// Note: The head time does not necessarily have to be an actual event
+    /// time present in this History. It can be any valid time that defines
+    /// the causal "cut" for this branch.
+    pub fn head_time(&self) -> T::Time {
+        self.head_time
+    }
+
+    pub fn into_history(self) -> T::History {
+        self.history
+    }
+}

src/list/raxos/protocal/src/apaxos/decided.rs

@@ -1,4 +1,4 @@
-use crate::apaxos::focal_history::FocalHistory;
-use crate::apaxos::focal_history::WITH_CURRENT_EVENT;
+use crate::apaxos::branch::Branch;
+use crate::apaxos::branch::HEAD_SET;
 
-pub type Decided<T> = FocalHistory<T, { WITH_CURRENT_EVENT }>;
+pub type Decided<T> = Branch<T, { HEAD_SET }>;

src/list/raxos/protocal/src/apaxos/history.rs

@@ -1,7 +1,7 @@
 use std::fmt::Debug;
 
+use crate::apaxos::branch::Branch;
 use crate::apaxos::errors::TimeRegression;
-use crate::apaxos::focal_history::FocalHistory;
 use crate::Types;
 
 /// A [`History`] contains [`Time`] and [`Event`] in a Partially Ordered Set.
@@ -36,9 +36,9 @@ where
 
     /// Returns a view(subset) of the history that is causally prior to or
     /// concurrent with the given `time`.
-    fn history_view(&self, time: T::Time) -> FocalHistory<T> {
+    fn history_view(&self, time: T::Time) -> Branch<T> {
         let lower = self.lower_bounds(time);
-        FocalHistory::new(time, lower)
+        Branch::new(time, lower)
     }
 
     /// Return a new instance in which every [`Time`] in it is causally prior to

src/list/raxos/protocal/src/apaxos/mod.rs

@@ -1,6 +1,6 @@
 pub mod acceptor;
+pub mod branch;
 pub mod errors;
-pub mod focal_history;
 pub mod history;
 pub mod proposal;
 pub mod proposer;

src/list/raxos/protocal/src/apaxos/proposer/mod.rs

@@ -1,8 +1,8 @@
 use phase1::Phase1;
 use phase2::Phase2;
 
+use crate::apaxos::branch::Branch;
 use crate::apaxos::errors::APError;
-use crate::apaxos::focal_history::FocalHistory;
 use crate::APaxos;
 use crate::Types;
 
@@ -44,7 +44,7 @@ impl<'a, T: Types> Proposer<'a, T> {
         }
     }
 
-    fn new_phase2(&mut self, maybe_committed: FocalHistory<T>) -> Phase2<T> {
+    fn new_phase2(&mut self, maybe_committed: Branch<T>) -> Phase2<T> {
         // If the current time already has an event, no new event is added.
 
         let decided = match maybe_committed.add_event(self.event.clone()) {

src/list/raxos/protocal/src/apaxos/proposer/phase1.rs

@@ -1,7 +1,7 @@
 use std::collections::BTreeMap;
 
+use crate::apaxos::branch::Branch;
 use crate::apaxos::errors::APError;
-use crate::apaxos::focal_history::FocalHistory;
 use crate::apaxos::history::History;
 use crate::APaxos;
 use crate::QuorumSet;
@@ -29,7 +29,7 @@ pub struct Phase1<'a, T: Types> {
 }
 
 impl<'a, T: Types> Phase1<'a, T> {
-    pub fn run(mut self) -> Result<FocalHistory<T>, APError<T>> {
+    pub fn run(mut self) -> Result<Branch<T>, APError<T>> {
         let apaxos = &mut self.apaxos;
 
         let mut sent = 0;
@@ -54,7 +54,7 @@ impl<'a, T: Types> Phase1<'a, T> {
                 self.apaxos.quorum_set.is_read_quorum(self.granted.keys().copied());
 
             if is_read_quorum {
-                let view = FocalHistory::new(self.time, self.previously_accepted);
+                let view = Branch::new(self.time, self.previously_accepted);
                 return Ok(view);
             }
         }

src/list/raxos/protocal/src/commonly_used/transport.rs

@@ -2,16 +2,16 @@ use std::collections::BTreeMap;
 use std::collections::VecDeque;
 
 use crate::apaxos::acceptor::Acceptor;
+use crate::apaxos::branch::Branch;
 use crate::apaxos::decided::Decided;
-use crate::apaxos::focal_history::FocalHistory;
 use crate::Transport;
 use crate::Types;
 
 /// Simulate network transport by delegate RPC to local function calls.
 pub struct DirectCall<T: Types> {
     acceptors: BTreeMap<T::AcceptorId, Acceptor<T>>,
 
-    p1_replies: VecDeque<(T::AcceptorId, Result<FocalHistory<T>, T::Time>)>,
+    p1_replies: VecDeque<(T::AcceptorId, Result<Branch<T>, T::Time>)>,
     p2_replies: VecDeque<(T::AcceptorId, Result<(), T::Time>)>,
 }
 
@@ -33,7 +33,7 @@ impl<T: Types> Transport<T> for DirectCall<T> {
         self.p1_replies.push_back((target, reply));
     }
 
-    fn recv_phase1_reply(&mut self) -> (T::AcceptorId, Result<FocalHistory<T>, T::Time>) {
+    fn recv_phase1_reply(&mut self) -> (T::AcceptorId, Result<Branch<T>, T::Time>) {
         self.p1_replies.pop_front().unwrap()
     }
 

src/list/raxos/protocal/src/lib.rs

@@ -10,8 +10,8 @@ use std::fmt::Debug;
 
 use apaxos::ptime::Time;
 
+use crate::apaxos::branch::Branch;
 use crate::apaxos::decided::Decided;
-use crate::apaxos::focal_history::FocalHistory;
 use crate::apaxos::history::History;
 
 pub trait AcceptorId: Debug + Clone + Copy + Ord + 'static {}
@@ -54,7 +54,7 @@ where Self: Default + Debug + Clone + Sized + 'static
 
 pub trait Transport<T: Types> {
     fn send_phase1_request(&mut self, target: T::AcceptorId, t: T::Time);
-    fn recv_phase1_reply(&mut self) -> (T::AcceptorId, Result<FocalHistory<T>, T::Time>);
+    fn recv_phase1_reply(&mut self) -> (T::AcceptorId, Result<Branch<T>, T::Time>);
 
     fn send_phase2_request(&mut self, target: T::AcceptorId, decided: Decided<T>);
     fn recv_phase2_reply(&mut self) -> (T::AcceptorId, Result<(), T::Time>);