git.iko.soy/distributed-process
on master help sign in
Add documentation about Transports.
c37ad23Nicolas Wu
network-transport/src/Network/Transport.hs+41−34
compare with master
unifiedsplit
@@ -1,89 +1,96 @@
1module Network.Transport
1module Network.Transport
2− ( Transport (..)
2+ ( Hints (..)
3+ , ReceiveEnd (..)
3 , SendAddr (..)
4 , SendAddr (..)
4 , SendEnd (..)
5 , SendEnd (..)
5− , ReceiveEnd (..)
6− , Hints (..)
7− , defaultHints
8 , SendHints (..)
6 , SendHints (..)
7+ , Transport (..)
8+ , connect
9+ , defaultHints
9 , defaultSendHints
10 , defaultSendHints
10 , newConnection
11 , newConnection
11 , newMulticast
12 , newMulticast
12− , connect
13 ) where
13 ) where
14
14
15import Data.ByteString.Char8 (ByteString)
15import Data.ByteString.Char8 (ByteString)
16
16
17−------------------------
17+-- | The `Hints` and `SendHints` provide hints to the underlying transport
18−-- Transport interface
18+-- about the kind of connection that is required. This might include details
19−--
19+-- such as whether the connection is eager or buffered, and the buffer size.
20−
21−-- Buffer size
22−-- Sending: eager or buffered
23−-- Big record of defaults
24data Hints = Hints
20data Hints = Hints
25data SendHints = SendHints
21data SendHints = SendHints
26
22
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.
27data Transport = Transport
32data Transport = Transport
28 { newConnectionWith :: Hints -> IO (SendAddr, ReceiveEnd)
33 { newConnectionWith :: Hints -> IO (SendAddr, ReceiveEnd)
29 , newMulticastWith :: Hints -> IO (MulticastSendEnd, MulticastReceiveAddr)
34 , newMulticastWith :: Hints -> IO (MulticastSendEnd, MulticastReceiveAddr)
30 , deserialize :: ByteString -> Maybe SendAddr
35 , deserialize :: ByteString -> Maybe SendAddr
31 }
36 }
32
37
38+-- | This is a convenience function that creates a new connection on a transport
39+-- using the default hints.
33newConnection :: Transport -> IO (SendAddr, ReceiveEnd)
40newConnection :: Transport -> IO (SendAddr, ReceiveEnd)
34newConnection transport = newConnectionWith transport defaultHints
41newConnection transport = newConnectionWith transport defaultHints
35
42
36newMulticast :: Transport -> IO (MulticastSendEnd, MulticastReceiveAddr)
43newMulticast :: Transport -> IO (MulticastSendEnd, MulticastReceiveAddr)
37newMulticast transport = newMulticastWith transport defaultHints
44newMulticast transport = newMulticastWith transport defaultHints
38
45
46+-- | The default `Hints` for establishing a new transport connection.
39defaultHints :: Hints
47defaultHints :: Hints
40defaultHints = Hints
48defaultHints = Hints
41
49
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.
42data SendAddr = SendAddr
55data SendAddr = SendAddr
43 { connectWith :: SendHints -> IO SendEnd
56 { connectWith :: SendHints -> IO SendEnd
44 , serialize :: ByteString
57 , serialize :: ByteString
45 }
58 }
46
59
60+-- | This is a convenience function that connects with a given `SendAddr` using
61+-- the default hints for sending.
47connect :: SendAddr -> IO SendEnd
62connect :: SendAddr -> IO SendEnd
48connect sendAddr = connectWith sendAddr defaultSendHints
63connect sendAddr = connectWith sendAddr defaultSendHints
49
64
65+-- | The default `SendHints` for establishing a `SendEnd`.
50defaultSendHints :: SendHints
66defaultSendHints :: SendHints
51defaultSendHints = SendHints
67defaultSendHints = SendHints
52
68
53−-- Send and receive are vectored
69+-- | A `SendEnd` provides a `send` function that allows vectored messages
70+-- to be sent to the corresponding `ReceiveEnd`.
54−data SendEnd = SendEnd
71+newtype SendEnd = SendEnd
55− { send :: [ByteString] -> IO ()
72+ { send :: [ByteString] -> IO ()
56− -- , sendAddress :: SendAddr
57 }
73 }
58
74
75+-- | A `ReceiveEnd` provides a `receive` function that allows messages
76+-- to be received from the corresponding `SendEnd`s.
59newtype ReceiveEnd = ReceiveEnd
77newtype ReceiveEnd = ReceiveEnd
60− { receive :: IO [ByteString]
78+ { receive :: IO [ByteString]
61− -- , receiveAddress :: SendAddr
62 }
79 }
63
80
64−data MulticastSendEnd = MulticastSendEnd
81+newtype MulticastSendEnd = MulticastSendEnd
65 { multicastSend :: ByteString -> IO ()
82 { multicastSend :: ByteString -> IO ()
66 }
83 }
67
84
68−data MulticastReceiveAddr = MulticastReceiveAddr
85+newtype MulticastReceiveAddr = MulticastReceiveAddr
69 { multicastConnect :: IO MulticastReceiveEnd
86 { multicastConnect :: IO MulticastReceiveEnd
70 }
87 }
71
88
72−data MulticastReceiveEnd = MulticastReceiveEnd
89+newtype MulticastReceiveEnd = MulticastReceiveEnd
73 { multicastReceive :: IO ByteString
90 { multicastReceive :: IO ByteString
74 }
91 }
75
92
93+-- TODO: Other SendEnds that might be of use:
76−-- data UnorderedSendEnd -- this is reliable
94+-- data UnorderedSendEnd -- reliable, unordered
77−-- data UnreliableSendEnd -- this is also unordered
95+-- data UnreliableSendEnd -- unreliable, 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
89
96