From fc871868c05c152c47e716e0f5271d62276ceebb Mon Sep 17 00:00:00 2001 From: Joe Crayne Date: Sat, 8 Sep 2018 00:43:34 -0400 Subject: Documented Network.Lossless. --- src/Network/Lossless.hs | 28 ++++++++++++++++++---------- 1 file changed, 18 insertions(+), 10 deletions(-) (limited to 'src') diff --git a/src/Network/Lossless.hs b/src/Network/Lossless.hs index f48dc8fd..ff0b8cc1 100644 --- a/src/Network/Lossless.hs +++ b/src/Network/Lossless.hs @@ -1,3 +1,9 @@ +-- | This module uses 'Data.PacketBuffer' appropriately to implement a reliable +-- transport over an underlying lossy one. +-- +-- It was written to be a helper to 'Network.Tox.Session' but it is +-- representation-agnostic and so could potentially be used on an unrelated +-- lossy transport. {-# LANGUAGE CPP #-} {-# LANGUAGE LambdaCase #-} {-# LANGUAGE TupleSections #-} @@ -19,21 +25,23 @@ import Control.Concurrent.Lifted.Instrument import Control.Concurrent.Lifted #endif +-- | Sequencing information for a packet. data SequenceInfo = SequenceInfo - { sequenceNumber :: {-# UNPACK #-} !Word32 - , sequenceAck :: {-# UNPACK #-} !Word32 + { sequenceNumber :: {-# UNPACK #-} !Word32 -- ^ Packets are ordered by their 'sequenceNumber'. + , sequenceAck :: {-# UNPACK #-} !Word32 -- ^ This is the sender's latest received in-order packet. } deriving (Eq,Ord,Show) +-- | Obtain a reliable transport form an unreliable one. lossless :: Show addr => - (x -> addr -> IO (PacketInboundEvent (x',addr'))) - -> (SequenceInfo -> x' -> addr' -> IO (Bool,y)) - -> addr - -> TransportA String addr x y - -> IO ( Transport String addr' x' - , [Word32] -> IO () - , IO ([Word32],Word32) - ) + (x -> addr -> IO (PacketInboundEvent (x',addr'))) -- ^ Used to classify newly arrived packets. + -> (SequenceInfo -> x' -> addr' -> IO (Bool,y)) -- ^ Used to encode and classify outbound packets. + -> addr -- ^ The remote address for this session. + -> TransportA String addr x y -- ^ An unreliable lossy transport. + -> IO ( Transport String addr' x' -- ^ A reliable lossless transport. + , [Word32] -> IO () -- ^ Use this to request lost packets be re-sent. + , IO ([Word32],Word32) -- ^ Use this to discover missing packets to request. + ) lossless isLossless encode saddr udp = do pb <- atomically newPacketBuffer oob <- atomically newTChan -- Out-of-band channel, these packets (or -- cgit v1.2.3