Network.Transport

A Transport abstracts the details of message delivery, and defines the interfaces that specific Transport implementations should provide in order to move messages between Endpoints.

The definition of a transport is deliberately low-level in nature. Unless a specific transport describes itself as supporting features like guaranteed delivery, applications should NOT assume that message delivery is reliable.

For example, if a sender sends a message to a name that has not yet been bound, then immediately waits on the response for that message, then the application may hang, as the original message may have been dropped.

However, many application may find it easier to push features such as reliable message delivery into a custom transport, leaving the application only having to concern itself with the messages being delivered rather than how they arrive.

The main abstractions common to all transports:

• Endpoints may not receive messages until either bind has been called on an available Transport, or a bindName has been called on the Endpoint. The latter is typically useful for Endpoints that originate connections but do not accept them directly.
• A Connection defines a bi-directional pathway for messages to flow between Endpoints. The initiator of the connection is a client, and the destination for the connection is a server. Server Endpoints may have to have called bind on the Transport before being able to accept connections or receive messages; a client only has to have called bindName in order to receive responses from the server.
• Client's proactively attempt to maintain Connections to the server; in the event a server breaks the connection (other because of a crash or deliberate exit), the client will continue to restore the connection.
• Connections essentially define the topology over which messages will propagate between Endpoints.

Transport

data Transport

A Transport defines a specific method for establishing connections between Endpoints.

Constructors

Transport

Fields

• bind :: Endpoint -> Name -> IO Binding
• dispatch :: Endpoint -> IO Dispatcher
• connect :: Endpoint -> Name -> IO Connection
• shutdown :: IO ()

data TransportException

An exception encountered by a Transport.

Constructors

NoDataRead

DataUnderflow

Instances

Show TransportException

Methods

showsPrec :: Int -> TransportException -> ShowS

show :: TransportException -> String

showList :: [TransportException] -> ShowS

Exception TransportException

Methods

toException :: TransportException -> SomeException

fromException :: SomeException -> Maybe TransportException

displayException :: TransportException -> String

data Dispatcher

A Dispatcher encapsulates a Transports interaction with an Endpoint for outbound message flow.

Constructors

Dispatcher

Fields

• stop :: IO ()

dispatcher :: Mailboxes -> Endpoint -> IO Dispatcher

Wraps in a continually repeating call to dispatchMessage in a Dispatcher so that dispatching can be stopped when no longer needed.

type Mailboxes = TVar (Map Name (Mailbox Message))

A mutable Map of Names to Mailboxes of Messages.

pullMessage :: Mailboxes -> Name -> STM Message

Pull a Message intended for a destination name from a Mailboxes directly, without the use of a Transport

dispatchMessage :: Mailboxes -> Name -> Message -> STM ()

A simple function to multiplex messages (each wrapped in an Envelope) in the endpointOutbound mailbox of an Endpoint to one or more Mailboxes by extract the messageDestination from the Envelope and finding or creating a Mailbox containing messages only for that destination. This is often useful for Transports, who then only have to monitor a specific Mailbox to know when there are messages to send to a particular destination.

withTransport :: IO Transport -> (Transport -> IO a) -> IO a

Within the body of the function, ensures that Messages are dispatched as necessary.

withEndpoint :: Transport -> Endpoint -> IO a -> IO a

Within the body of the function, ensure that there is a Dispatcher for the Endpoint.

data Binding

Bindings are a site for receiving messages on a particular Name through a Transport.

Constructors

Binding

Fields

• bindingName :: Name
• unbind :: IO ()

withBinding :: Transport -> Endpoint -> Name -> IO a -> IO a

A helper for ensuring there is a Binding of a specific Endpoint to a specific Name on the provided Transport during a function.

withBinding2 :: Transport -> (Endpoint, Name) -> (Endpoint, Name) -> IO a -> IO a

A helper for ensuring there are Bindings of a specific Endpoint to specific Names on the provided Transport during a function.

withBinding3 :: Transport -> (Endpoint, Name) -> (Endpoint, Name) -> (Endpoint, Name) -> IO a -> IO a

A helper for ensuring there are Bindings of a specific Endpoint to specific Names on the provided Transport during a function.

withBinding4 :: Transport -> (Endpoint, Name) -> (Endpoint, Name) -> (Endpoint, Name) -> (Endpoint, Name) -> IO a -> IO a

A helper for ensuring there are Bindings of a specific Endpoint to specific Names on the provided Transport during a function.

data Connection

Connections are bi-directional pathways for exchanging Messages with another Endpoint that is bound to a specific Name on a shared Transport.

Constructors

Connection

Fields

• disconnect :: IO ()

withConnection :: Transport -> Endpoint -> Name -> IO a -> IO a

A helper for ensuring that a Connection is maintained during execution of a function.

withConnection2 :: Transport -> Endpoint -> Name -> Name -> IO a -> IO a

A helper for ensuring that 2 Connections are maintained during execution of a function.

withConnection3 :: Transport -> Endpoint -> Name -> Name -> Name -> IO a -> IO a

A helper for ensuring that 3 Connections are maintained during execution of a function.

withConnection4 :: Transport -> Endpoint -> Name -> Name -> Name -> Name -> IO a -> IO a

A helper for ensuring that 4 Connections are maintained during execution of a function.

withConnections :: Transport -> Endpoint -> [Name] -> IO a -> IO a

withCompleteNetwork :: Transport -> [Name] -> Endpoint -> Name -> IO a -> IO a

This is a helper designed to create a complete network, where there are enough connections to ensure every endpoint has a connection to every other endpoint.