updated docs

README.md

@@ -0,0 +1,34 @@
+# Sequential Exchange Protocol
+
+The reference implementation of the **Sequential Exchange Protocol**, or SEP.
+
+SEP is a peer-to-peer transport protocol that guarantees packets of data will always be received
+in the same order they were sent. In addition, it also guarantees the sequential consistency of
+stateful exchanges between the two communicating peers.
+
+A "stateful exchange" is defined here as a sequence of packets, where the first packet
+initiates the exchange, and all subsequent packets are replies to the previous packet in the
+exchange.
+
+SEP guarantees both peers will agree upon which packets are members of which exchanges,
+and it guarantees each packet is received by each peer in sequential order.
+
+SEP is a tiny, dead simple protocol and we have implemented it here in less than 500 lines of code.
+
+## Why not TCP?
+
+TCP only guarantees packets will be received in the same order they were sent.
+It has no inherent concept of "replying to a packet" and as such it cannot guarantee both sides
+of a conversation have the same view of any stateful exchanges that take place.
+
+TCP is also much higher overhead. It requires a 1.5 RTT handshake to begin any connection,
+it has a larger amount of metadata that must be transported with packets, and it has quite a few
+features that slow down runtime regardless of whether or not they are used.
+A lot of this overhead owes to TCPs sizeable complexity.
+
+That being said SEP does lack many of TCP's additional features, such as a dynamic resend timer,
+keep-alives, and expiration handling. This can be both a pro and a con, as it means there is a
+lot of efficiency to be gained if these features are not needed or are implemented at a
+different protocol layer.
+
+Neither SEP nor TCP are cryptographically secure.

src/lib.rs

@@ -13,7 +13,7 @@
 //!
 //! SEP is a tiny, dead simple protocol and we have implemented it here in less than 500 lines of code.
 //!
-//! # Why not TCP?
+//! ## Why not TCP?
 //!
 //! TCP only guarantees packets will be received in the same order they were sent.
 //! It has no inherent concept of "replying to a packet" and as such it cannot guarantee both sides
@@ -31,7 +31,7 @@
 //!
 //! Neither SEP nor TCP are cryptographically secure.
 //!
-//! # Examples
+//! ## Examples
 //!
 #![no_std]
 #![forbid(unsafe_code)]
@@ -63,7 +63,7 @@ impl<TL: TransportLayer> IntoRecvData<TL> for TL::RecvData {
     }
 }
 
-pub struct SeqQueue<TL: TransportLayer, const SLEN: usize = 64, const RLEN: usize = 32> {
+pub struct SeqEx<TL: TransportLayer, const SLEN: usize = 64, const RLEN: usize = 32> {
     pub retry_interval: i64,
     next_send_seq_num: SeqNum,
     pre_recv_seq_num: SeqNum,
@@ -93,14 +93,14 @@ pub enum Error {
 /// If it is dropped without calling `reply` an empty reply will be sent to the remote peer.
 pub struct ReplyGuard<'a, TL: TransportLayer> {
     app: Option<&'a TL>,
-    seq_queue: &'a mut SeqQueue<TL>,
+    seq_queue: &'a mut SeqEx<TL>,
     reply_num: SeqNum,
 }
 
 pub struct Iter<'a, TL: TransportLayer>(core::slice::Iter<'a, Option<SendEntry<TL>>>);
 pub struct IterMut<'a, TL: TransportLayer>(core::slice::IterMut<'a, Option<SendEntry<TL>>>);
 
-impl<TL: TransportLayer> SeqQueue<TL> {
+impl<TL: TransportLayer> SeqEx<TL> {
     pub fn new(retry_interval: i64, initial_seq_num: SeqNum) -> Self {
         Self {
             retry_interval,
@@ -287,7 +287,7 @@ impl<TL: TransportLayer> SeqQueue<TL> {
         IterMut(self.send_window.iter_mut())
     }
 }
-impl<'a, TL: TransportLayer> IntoIterator for &'a SeqQueue<TL> {
+impl<'a, TL: TransportLayer> IntoIterator for &'a SeqEx<TL> {
     type Item = &'a TL::SendData;
     type IntoIter = Iter<'a, TL>;
 
@@ -295,7 +295,7 @@ impl<'a, TL: TransportLayer> IntoIterator for &'a SeqQueue<TL> {
         self.iter()
     }
 }
-impl<'a, TL: TransportLayer> IntoIterator for &'a mut SeqQueue<TL> {
+impl<'a, TL: TransportLayer> IntoIterator for &'a mut SeqEx<TL> {
     type Item = &'a mut TL::SendData;
     type IntoIter = IterMut<'a, TL>;