Network.Endpoints

Endpoints are a generalized abstraction for communication between parts of a program, whether on the same physical host or distributed over a network. Endpoints are intended to simplify the development of network-centric applications by providing a small transport-independent message-passing interface, and application writers can independently alter their implementation by enabling their Endpoints with different Transports without modifying the logic of their application that sends / receives Messages.

How to use courier in an application

A sample of how to use this library:

 -- Just import this package to access the primary APIs
 import Network.Endpoints

 -- A specific transport is necessary, however
 import Network.Transport.TCP
 
 helloWorld :: IO ()
 helloWorld = do
   let name1 = "endpoint1"b
       name2 = "endpoint2"
       resolver = resolverFromList [(name1,"localhost:2000"),
                                    (name2,"localhost:2001")]
   transport <- newTCPTransport resolver
   endpoint1 <- newEndpoint [transport]
   endpoint2 <- newEndpoint [transport]
   Right () <- bindEndpoint endpoint1 name1
   Right () <- bindEndpoint endpoint2 name2
   sendMessage endpoint1 name2 $ encode "hello world!"
   msg <- receiveMessage endpoint2
   print msg
   shutdown transport

Primary API

data Endpoint

Endpoints are a locus of communication, used for sending and receive messages.

newEndpoint :: [Transport] -> IO Endpoint

Create a new Endpoint using the provided transports.

bindEndpoint :: Endpoint -> Name -> IO (Either String ())

Binding an Endpoint to a Name prepares the Endpoint to receive messages sent to the bound name. Upon success, the result will be Right (), but if failed, Left text-of-error-message.

unbindEndpoint :: Endpoint -> Name -> IO (Either String ())

Unbind an Endpoint from a Name, after which the Endpoint will eventually not receive messages sent to that Name. Note that there is no guarantee that after Unbind succeeds that additional messages to that Name will not be delivered: the only guarantee is that eventually messages will no longer be delivered. Upon success, the result will be Right () but if failed, Left text-of-error-message.

sendMessage :: Endpoint -> Name -> Message -> IO (Either String ())

Send a Message to specific Name via the indicated Endpoint. While a successful response (indicated by returning Right ()) indicates that there was no error initiating transport of the message, success does not guarantee that an Endpoint received the message. Failure initiating transport is indicated by returning Left text-of-error-message.

sendMessage_ :: Endpoint -> Name -> Message -> IO ()

A variant of sendMessage for use when the return value can be ignored.

broadcastMessage :: Endpoint -> [Name] -> Message -> IO [Either String ()]

Helper for sending a single Message to several Endpoints.

broadcastMessage_ :: Endpoint -> [Name] -> Message -> IO ()

Variant of broadcastMessage that ignores the results of sending.

receiveMessage :: Endpoint -> IO Message

Receive the next Message sent to the Endpoint, blocking until a message is available.

receiveMessageTimeout :: Endpoint -> Int -> IO (Maybe Message)

Wait for a message to be received within the timeout, blocking until either a message is available or the timeout has occurred. If a message was available, returns Just message, but returns Nothing if no message available before the timeout occurred.

Transports

Transports define specific implementations of message-passing techniques (e.g., memory-based, TCP, UDP, HTTP, etc.). Typical use of the Endpoints does not require direct use of Transports, beyond creating specific Transports (such as found in Network.Transport.Memory and Network.Transport.TCP) and adding them to an Endpoint.

module Network.Transport