@@ -9,6 +9,9 @@ module Network.Transport ( -- * Types
9 , MulticastGroup(..)
9 , MulticastGroup(..)
10 , EndPointAddress(..)
10 , EndPointAddress(..)
11 , MulticastAddress(..)
11 , MulticastAddress(..)
14+ , defaultConnectHints
12 -- * Error codes
15 -- * Error codes
13 , TransportError(..)
16 , TransportError(..)
14 , NewEndPointErrorCode(..)
17 , NewEndPointErrorCode(..)
@@ -43,7 +46,7 @@ data EndPoint = EndPoint {
43 -- | EndPointAddress of the endpoint.
46 -- | EndPointAddress of the endpoint.
44 , address :: EndPointAddress
47 , address :: EndPointAddress
45 -- | Create a new lightweight connection.
48 -- | Create a new lightweight connection.
46− , connect :: EndPointAddress -> Reliability -> IO (Either (TransportError ConnectErrorCode) Connection)
49+ , connect :: EndPointAddress -> Reliability -> ConnectHints -> IO (Either (TransportError ConnectErrorCode) Connection)
47 -- | Create a new multicast group.
50 -- | Create a new multicast group.
48 , newMulticastGroup :: IO (Either (TransportError NewMulticastGroupErrorCode) MulticastGroup)
51 , newMulticastGroup :: IO (Either (TransportError NewMulticastGroupErrorCode) MulticastGroup)
49 -- | Resolve an address to a multicast group.
52 -- | Resolve an address to a multicast group.
@@ -76,7 +79,7 @@ data Event =
76 | ErrorEvent (TransportError EventErrorCode)
79 | ErrorEvent (TransportError EventErrorCode)
77 deriving Show
80 deriving Show
79−-- | Connection IDs enable receivers to distinguish one connection from another.
82+-- | Connection data ConnectHintsIDs enable receivers to distinguish one connection from another.
80type ConnectionId = Int
83type ConnectionId = Int
82-- | Reliability guarantees of a connection.
85-- | Reliability guarantees of a connection.
@@ -118,10 +121,31 @@ newtype MulticastAddress = MulticastAddress { multicastAddressToByteString :: By
118instance Show MulticastAddress where
121instance Show MulticastAddress where
119 show = show . multicastAddressToByteString
122 show = show . multicastAddressToByteString
124+--------------------------------------------------------------------------------
127+-- Hints provide transport-generic "suggestions". For now, these are --
128+-- placeholders only. --
129+--------------------------------------------------------------------------------
131+-- Hints used by 'connect'
134+-- Default hints for connecting
135+defaultConnectHints :: ConnectHints
136+defaultConnectHints = undefined
121--------------------------------------------------------------------------------
138--------------------------------------------------------------------------------
122-- Error codes --
139-- Error codes --
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 --
123--------------------------------------------------------------------------------
145--------------------------------------------------------------------------------
147+-- | Errors returned by Network.Transport API functions consist of an error
148+-- code and a human readable description of the problem
125data TransportError error = TransportError error String
149data TransportError error = TransportError error String
126 deriving (Show, Typeable)
150 deriving (Show, Typeable)
@@ -133,33 +157,26 @@ instance (Typeable err, Show err) => Exception (TransportError err)
133-- | Errors during the creation of an endpoint
157-- | Errors during the creation of an endpoint
134data NewEndPointErrorCode =
158data NewEndPointErrorCode =
135 -- | Not enough resources
159 -- | Not enough resources
136− -- (i.e., this could be a temporary local problem)
137 NewEndPointInsufficientResources
160 NewEndPointInsufficientResources
138 -- | Failed for some other reason
161 -- | Failed for some other reason
139− -- (i.e., there is probably no point trying again)
140 | NewEndPointFailed
162 | NewEndPointFailed
141 deriving (Show, Typeable)
163 deriving (Show, Typeable)
143-- | Connection failure
165-- | Connection failure
144data ConnectErrorCode =
166data ConnectErrorCode =
145 -- | Could not resolve the address
167 -- | Could not resolve the address
146− -- (i.e., this could be a temporary remote problem)
147 ConnectNotFound
168 ConnectNotFound
148 -- | Insufficient resources (for instance, no more sockets available)
169 -- | Insufficient resources (for instance, no more sockets available)
149− -- (i.e., this could be a temporary local problem)
150 | ConnectInsufficientResources
170 | ConnectInsufficientResources
151 -- | Failed for other reasons (including syntax error)
171 -- | Failed for other reasons (including syntax error)
152− -- (i.e., there is probably no point trying again).
153 | ConnectFailed
172 | ConnectFailed
154 deriving (Show, Typeable)
173 deriving (Show, Typeable)
156-- | Failure during the creation of a new multicast group
175-- | Failure during the creation of a new multicast group
157data NewMulticastGroupErrorCode =
176data NewMulticastGroupErrorCode =
158 -- | Insufficient resources
177 -- | Insufficient resources
159− -- (i.e., this could be a temporary problem)
160 NewMulticastGroupInsufficientResources
178 NewMulticastGroupInsufficientResources
161 -- | Failed for some other reason
179 -- | Failed for some other reason
162− -- (i.e., there is probably no point trying again)
163 | NewMulticastGroupFailed
180 | NewMulticastGroupFailed
164 -- | Not all transport implementations support multicast
181 -- | Not all transport implementations support multicast
165 | NewMulticastGroupUnsupported
182 | NewMulticastGroupUnsupported
@@ -168,10 +185,8 @@ data NewMulticastGroupErrorCode =
168-- | Failure during the resolution of a multicast group
185-- | Failure during the resolution of a multicast group
169data ResolveMulticastGroupErrorCode =
186data ResolveMulticastGroupErrorCode =
170 -- | Multicast group not found
187 -- | Multicast group not found
171− -- (i.e., this could be a temporary problem)
172 ResolveMulticastGroupNotFound
188 ResolveMulticastGroupNotFound
173 -- | Failed for some other reason (including syntax error)
189 -- | Failed for some other reason (including syntax error)
174− -- (i.e., there is probably no point trying again)
175 | ResolveMulticastGroupFailed
190 | ResolveMulticastGroupFailed
176 -- | Not all transport implementations support multicast
191 -- | Not all transport implementations support multicast
177 | ResolveMulticastGroupUnsupported
192 | ResolveMulticastGroupUnsupported
@@ -179,11 +194,9 @@ data ResolveMulticastGroupErrorCode =
180-- | Failure during sending a message
195-- | Failure during sending a message
181data SendErrorCode =
196data SendErrorCode =
182− -- | Could not send this message
197+ -- | Connection was closed
183− -- (but another attempt might succeed)
198+ SendClosed
185 -- | Send failed for some other reason
199 -- | Send failed for some other reason
186− -- (and retrying probably won't help)
187 | SendFailed
200 | SendFailed
188 deriving (Show, Typeable)
201 deriving (Show, Typeable)