network-transport-0.4.2.0: Network abstraction layer

Safe HaskellNone
LanguageHaskell98

Network.Transport

Contents

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

ConnectionIds 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

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

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

newtype MulticastAddress Source

EndPointAddress of a multicast group.

Constructors

MulticastAddress 

Fields

multicastAddressToByteString :: ByteString
 

Instances

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

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.

Typeable (* -> *) TransportError 

data NewEndPointErrorCode Source

Errors during the creation of an endpoint

Constructors

NewEndPointInsufficientResources

Not enough resources

NewEndPointFailed

Failed for some other reason

Instances

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

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

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

data SendErrorCode Source

Failure during sending a message

Constructors

SendClosed

Connection was closed

SendFailed

Send failed for some other reason

Instances

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