Safe Haskell	None

Network.Transport

Contents

Types
Hints
Error codes

Description

Network Transport

Synopsis

Types

data Transport Source

To create a network abstraction layer, use one of the Network.Transport.* packages.

Constructors

Transport
Fields newEndPoint :: IO (Either (TransportError NewEndPointErrorCode) EndPoint) Create a new end point (heavyweight operation) closeTransport :: IO () Shutdown the transport completely

data EndPoint Source

Network endpoint.

Constructors

EndPoint

Fields

receive :: IO Event

Endpoints have a single shared receive queue.

address :: EndPointAddress

EndPointAddress of the endpoint.

connect :: EndPointAddress -> Reliability -> ConnectHints -> IO (Either (TransportError ConnectErrorCode) Connection)

Create a new lightweight connection.

connect should be as asynchronous as possible; for instance, in Transport implementations based on some heavy-weight underlying network protocol (TCP, ssh), a call to connect should be asynchronous when a heavyweight connection has already been established.

newMulticastGroup :: IO (Either (TransportError NewMulticastGroupErrorCode) MulticastGroup)

Create a new multicast group.

resolveMulticastGroup :: MulticastAddress -> IO (Either (TransportError ResolveMulticastGroupErrorCode) MulticastGroup)

Resolve an address to a multicast group.

closeEndPoint :: IO ()

Close the endpoint

data Connection Source

Lightweight connection to an endpoint.

Constructors

Connection
Fields send :: [ByteString] -> IO (Either (TransportError SendErrorCode) ()) Send a message on this connection. `send` provides vectored I/O, and allows multiple data segments to be sent using a single call (cf. `sendMany`). Note that this segment structure is entirely unrelated to the segment structure returned by a `Received` event. close :: IO () Close the connection.

data Event Source

Event on an endpoint.

Constructors

Received !ConnectionId [ByteString]	Received a message
ConnectionClosed !ConnectionId	Connection closed
ConnectionOpened !ConnectionId Reliability EndPointAddress	Connection opened `ConnectionId`s need not be allocated contiguously.
ReceivedMulticast MulticastAddress [ByteString]	Received multicast
EndPointClosed	The endpoint got closed (manually, by a call to closeEndPoint or closeTransport)
ErrorEvent (TransportError EventErrorCode)	An error occurred

Instances

Eq Event
Show Event

type ConnectionId = Word64 Source

Connection data ConnectHintsIDs enable receivers to distinguish one connection from another.

data Reliability Source

Reliability guarantees of a connection.

Constructors

ReliableOrdered
ReliableUnordered
Unreliable

Instances

Eq Reliability
Show Reliability
Typeable Reliability
Binary Reliability

data MulticastGroup Source

Multicast group.

Constructors

MulticastGroup

Fields

multicastAddress :: MulticastAddress: EndPointAddress of the multicast group.
deleteMulticastGroup :: IO (): Delete the multicast group completely.
maxMsgSize :: Maybe Int: Maximum message size that we can send to this group.
multicastSend :: [ByteString] -> IO (): Send a message to the group.
multicastSubscribe :: IO (): Subscribe to the given multicast group (to start receiving messages from the group).
multicastUnsubscribe :: IO (): Unsubscribe from the given multicast group (to stop receiving messages from the group).
multicastClose :: IO (): Close the group (that is, indicate you no longer wish to send to the group).

newtype EndPointAddress Source

EndPointAddress of an endpoint.

Constructors

EndPointAddress
Fields endPointAddressToByteString :: ByteString

Instances

Eq EndPointAddress
Ord EndPointAddress
Show EndPointAddress
Typeable EndPointAddress
Binary EndPointAddress
Hashable EndPointAddress

newtype MulticastAddress Source

EndPointAddress of a multicast group.

Constructors

MulticastAddress
Fields multicastAddressToByteString :: ByteString

Instances

Eq MulticastAddress
Ord MulticastAddress
Show MulticastAddress

Hints

data ConnectHints Source

Hints used by connect

Constructors

ConnectHints
Fields connectTimeout :: Maybe Int

defaultConnectHints :: ConnectHints Source

Default hints for connecting

Error codes

data TransportError error Source

Errors returned by Network.Transport API functions consist of an error code and a human readable description of the problem

Constructors

TransportError error String

Instances

Typeable1 TransportError
Eq error => Eq (TransportError error)	When comparing errors we ignore the human-readable strings
Show error => Show (TransportError error)
(Typeable err, Show err) => Exception (TransportError err)	Although the functions in the transport API never throw TransportErrors (but return them explicitly), application code may want to turn these into exceptions.

data NewEndPointErrorCode Source

Errors during the creation of an endpoint

Constructors

NewEndPointInsufficientResources	Not enough resources
NewEndPointFailed	Failed for some other reason

Instances

Eq NewEndPointErrorCode
Show NewEndPointErrorCode
Typeable NewEndPointErrorCode

data ConnectErrorCode Source

Connection failure

Constructors

ConnectNotFound	Could not resolve the address
ConnectInsufficientResources	Insufficient resources (for instance, no more sockets available)
ConnectTimeout	Timeout
ConnectFailed	Failed for other reasons (including syntax error)

Instances

Eq ConnectErrorCode
Show ConnectErrorCode
Typeable ConnectErrorCode

data NewMulticastGroupErrorCode Source

Failure during the creation of a new multicast group

Constructors

NewMulticastGroupInsufficientResources	Insufficient resources
NewMulticastGroupFailed	Failed for some other reason
NewMulticastGroupUnsupported	Not all transport implementations support multicast

Instances

Eq NewMulticastGroupErrorCode
Show NewMulticastGroupErrorCode
Typeable NewMulticastGroupErrorCode

data ResolveMulticastGroupErrorCode Source

Failure during the resolution of a multicast group

Constructors

ResolveMulticastGroupNotFound	Multicast group not found
ResolveMulticastGroupFailed	Failed for some other reason (including syntax error)
ResolveMulticastGroupUnsupported	Not all transport implementations support multicast

Instances

Eq ResolveMulticastGroupErrorCode
Show ResolveMulticastGroupErrorCode
Typeable ResolveMulticastGroupErrorCode

data SendErrorCode Source

Failure during sending a message

Constructors

SendClosed	Connection was closed
SendFailed	Send failed for some other reason

Instances

Eq SendErrorCode
Show SendErrorCode
Typeable SendErrorCode

data EventErrorCode Source

Error codes used when reporting errors to endpoints (through receive)

Constructors

EventEndPointFailed

Failure of the entire endpoint

EventTransportFailed

Transport-wide fatal error

EventConnectionLost EndPointAddress

We lost connection to another endpoint

Although Network.Transport provides multiple independent lightweight connections between endpoints, those connections cannot fail independently: once one connection has failed, all connections, in both directions, must now be considered to have failed; they fail as a bundle of connections, with only a single bundle of connections per endpoint at any point in time.

That is, suppose there are multiple connections in either direction between endpoints A and B, and A receives a notification that it has lost contact with B. Then A must not be able to send any further messages to B on existing connections.

Although B may not realize immediately that its connection to A has been broken, messages sent by B on existing connections should not be delivered, and B must eventually get an EventConnectionLost message, too.

Moreover, this event must be posted before A has successfully reconnected (in other words, if B notices a reconnection attempt from A, it must post the EventConnectionLost before acknowledging the connection from A) so that B will not receive events about new connections or incoming messages from A without realizing that it got disconnected.

If B attempts to establish another connection to A before it realized that it got disconnected from A then it's okay for this connection attempt to fail, and the EventConnectionLost to be posted at that point, or for the EventConnectionLost to be posted and for the new connection to be considered the first connection of the new bundle.

Instances

Eq EventErrorCode
Show EventErrorCode
Typeable EventErrorCode