@@ -1,89 +1,96 @@
11module Network.Transport
2− ( Transport (..)
2+ ( Hints (..)
3+ , ReceiveEnd (..)
34 , SendAddr (..)
45 , SendEnd (..)
5− , ReceiveEnd (..)
6− , Hints (..)
7− , defaultHints
86 , SendHints (..)
7+ , Transport (..)
8+ , connect
9+ , defaultHints
910 , defaultSendHints
1011 , newConnection
1112 , newMulticast
12− , connect
1313 ) where
1414
1515import Data.ByteString.Char8 (ByteString)
1616
17−------------------------
18−-- Transport interface
19−--
20−
21−-- Buffer size
22−-- Sending: eager or buffered
23−-- Big record of defaults
17+-- | The `Hints` and `SendHints` provide hints to the underlying transport
18+-- about the kind of connection that is required. This might include details
19+-- such as whether the connection is eager or buffered, and the buffer size.
2420data Hints = Hints
2521data SendHints = SendHints
2622
23+-- | A `Transport` encapsulates the functions required to establish many-to-one
24+-- and one-to-many connections between clients and servers.
25+-- The `newConnectionWith` function creates a `ReceiveEnd` that listens to
26+-- messages sent using the corresponding `SendAddr`. This connection is
27+-- established using a `Hints` value, which provides information about the
28+-- connection topology.
29+-- Each `SendAddr` can be serialised into a `ByteString`, and the `deserialize`
30+-- function converts this back into a `SendAddr`.
31+-- Note that these connections provide reliable and ordered messages.
2732data Transport = Transport
2833 { newConnectionWith :: Hints -> IO (SendAddr, ReceiveEnd)
2934 , newMulticastWith :: Hints -> IO (MulticastSendEnd, MulticastReceiveAddr)
3035 , deserialize :: ByteString -> Maybe SendAddr
3136 }
3237
38+-- | This is a convenience function that creates a new connection on a transport
39+-- using the default hints.
3340newConnection :: Transport -> IO (SendAddr, ReceiveEnd)
3441newConnection transport = newConnectionWith transport defaultHints
3542
3643newMulticast :: Transport -> IO (MulticastSendEnd, MulticastReceiveAddr)
3744newMulticast transport = newMulticastWith transport defaultHints
3845
46+-- | The default `Hints` for establishing a new transport connection.
3947defaultHints :: Hints
4048defaultHints = Hints
4149
50+-- | A `SendAddr` is an address that corresponds to a listening `ReceiveEnd`
51+-- initially created using `newConnection`. A `SendAddr` can be shared between
52+-- clients by using `serialize`, and passing the resulting `ByteString`.
53+-- Given a `SendAddr`, the `connectWith` function creates a `SendEnd` which
54+-- can be used to send messages.
4255data SendAddr = SendAddr
4356 { connectWith :: SendHints -> IO SendEnd
4457 , serialize :: ByteString
4558 }
4659
60+-- | This is a convenience function that connects with a given `SendAddr` using
61+-- the default hints for sending.
4762connect :: SendAddr -> IO SendEnd
4863connect sendAddr = connectWith sendAddr defaultSendHints
4964
65+-- | The default `SendHints` for establishing a `SendEnd`.
5066defaultSendHints :: SendHints
5167defaultSendHints = SendHints
5268
53−-- Send and receive are vectored
54−data SendEnd = SendEnd
55− { send :: [ByteString] -> IO ()
56− -- , sendAddress :: SendAddr
69+-- | A `SendEnd` provides a `send` function that allows vectored messages
70+-- to be sent to the corresponding `ReceiveEnd`.
71+newtype SendEnd = SendEnd
72+ { send :: [ByteString] -> IO ()
5773 }
5874
75+-- | A `ReceiveEnd` provides a `receive` function that allows messages
76+-- to be received from the corresponding `SendEnd`s.
5977newtype ReceiveEnd = ReceiveEnd
60− { receive :: IO [ByteString]
61− -- , receiveAddress :: SendAddr
78+ { receive :: IO [ByteString]
6279 }
6380
64−data MulticastSendEnd = MulticastSendEnd
81+newtype MulticastSendEnd = MulticastSendEnd
6582 { multicastSend :: ByteString -> IO ()
6683 }
6784
68−data MulticastReceiveAddr = MulticastReceiveAddr
85+newtype MulticastReceiveAddr = MulticastReceiveAddr
6986 { multicastConnect :: IO MulticastReceiveEnd
7087 }
7188
72−data MulticastReceiveEnd = MulticastReceiveEnd
89+newtype MulticastReceiveEnd = MulticastReceiveEnd
7390 { multicastReceive :: IO ByteString
7491 }
7592
76−-- data UnorderedSendEnd -- this is reliable
77−-- data UnreliableSendEnd -- this is also unordered
78−--
79−-- multicast is alwaysw unordered and unreliable
80−
81−-- TODO:
82−-- * Multicast
83−-- * Dual of the Transport: one to many, rather than many to one
84−-- * Optional: not supported by all transports
85−-- * Different transport types
86−-- * Unreliable
87−-- * Unordered
88−-- * Send / receive should be vectored
93+-- TODO: Other SendEnds that might be of use:
94+-- data UnorderedSendEnd -- reliable, unordered
95+-- data UnreliableSendEnd -- unreliable, unordered
8996