@@ -9,6 +9,9 @@ module Network.Transport ( -- * Types
99 , MulticastGroup(..)
1010 , EndPointAddress(..)
1111 , MulticastAddress(..)
12+ -- * Hints
13+ , ConnectHints
14+ , defaultConnectHints
1215 -- * Error codes
1316 , TransportError(..)
1417 , NewEndPointErrorCode(..)
@@ -43,7 +46,7 @@ data EndPoint = EndPoint {
4346 -- | EndPointAddress of the endpoint.
4447 , address :: EndPointAddress
4548 -- | Create a new lightweight connection.
46− , connect :: EndPointAddress -> Reliability -> IO (Either (TransportError ConnectErrorCode) Connection)
49+ , connect :: EndPointAddress -> Reliability -> ConnectHints -> IO (Either (TransportError ConnectErrorCode) Connection)
4750 -- | Create a new multicast group.
4851 , newMulticastGroup :: IO (Either (TransportError NewMulticastGroupErrorCode) MulticastGroup)
4952 -- | Resolve an address to a multicast group.
@@ -76,7 +79,7 @@ data Event =
7679 | ErrorEvent (TransportError EventErrorCode)
7780 deriving Show
7881
79−-- | Connection IDs enable receivers to distinguish one connection from another.
82+-- | Connection data ConnectHintsIDs enable receivers to distinguish one connection from another.
8083type ConnectionId = Int
8184
8285-- | Reliability guarantees of a connection.
@@ -118,10 +121,31 @@ newtype MulticastAddress = MulticastAddress { multicastAddressToByteString :: By
118121instance Show MulticastAddress where
119122 show = show . multicastAddressToByteString
120123
124+--------------------------------------------------------------------------------
125+-- Hints --
126+-- --
127+-- Hints provide transport-generic "suggestions". For now, these are --
128+-- placeholders only. --
129+--------------------------------------------------------------------------------
130+
131+-- Hints used by 'connect'
132+data ConnectHints
133+
134+-- Default hints for connecting
135+defaultConnectHints :: ConnectHints
136+defaultConnectHints = undefined
137+
121138--------------------------------------------------------------------------------
122139-- Error codes --
140+-- --
141+-- Errors should be transport-implementation independent. The deciding factor --
142+-- for distinguishing one kind of error from another should be: might --
143+-- application code have to take a different action depending on the kind of --
144+-- error? --
123145--------------------------------------------------------------------------------
124146
147+-- | Errors returned by Network.Transport API functions consist of an error
148+-- code and a human readable description of the problem
125149data TransportError error = TransportError error String
126150 deriving (Show, Typeable)
127151
@@ -133,33 +157,26 @@ instance (Typeable err, Show err) => Exception (TransportError err)
133157-- | Errors during the creation of an endpoint
134158data NewEndPointErrorCode =
135159 -- | Not enough resources
136− -- (i.e., this could be a temporary local problem)
137160 NewEndPointInsufficientResources
138161 -- | Failed for some other reason
139− -- (i.e., there is probably no point trying again)
140162 | NewEndPointFailed
141163 deriving (Show, Typeable)
142164
143165-- | Connection failure
144166data ConnectErrorCode =
145167 -- | Could not resolve the address
146− -- (i.e., this could be a temporary remote problem)
147168 ConnectNotFound
148169 -- | Insufficient resources (for instance, no more sockets available)
149− -- (i.e., this could be a temporary local problem)
150170 | ConnectInsufficientResources
151171 -- | Failed for other reasons (including syntax error)
152− -- (i.e., there is probably no point trying again).
153172 | ConnectFailed
154173 deriving (Show, Typeable)
155174
156175-- | Failure during the creation of a new multicast group
157176data NewMulticastGroupErrorCode =
158177 -- | Insufficient resources
159− -- (i.e., this could be a temporary problem)
160178 NewMulticastGroupInsufficientResources
161179 -- | Failed for some other reason
162− -- (i.e., there is probably no point trying again)
163180 | NewMulticastGroupFailed
164181 -- | Not all transport implementations support multicast
165182 | NewMulticastGroupUnsupported
@@ -168,10 +185,8 @@ data NewMulticastGroupErrorCode =
168185-- | Failure during the resolution of a multicast group
169186data ResolveMulticastGroupErrorCode =
170187 -- | Multicast group not found
171− -- (i.e., this could be a temporary problem)
172188 ResolveMulticastGroupNotFound
173189 -- | Failed for some other reason (including syntax error)
174− -- (i.e., there is probably no point trying again)
175190 | ResolveMulticastGroupFailed
176191 -- | Not all transport implementations support multicast
177192 | ResolveMulticastGroupUnsupported
@@ -179,11 +194,9 @@ data ResolveMulticastGroupErrorCode =
179194
180195-- | Failure during sending a message
181196data SendErrorCode =
182− -- | Could not send this message
183− -- (but another attempt might succeed)
184− SendUnreachable
197+ -- | Connection was closed
198+ SendClosed
185199 -- | Send failed for some other reason
186− -- (and retrying probably won't help)
187200 | SendFailed
188201 deriving (Show, Typeable)
189202