Portability | non-portable (requires STM) |
---|---|
Stability | experimental |
Maintainer | phil@haphazardhouse.net |
Safe Haskell | None |
Endpoint
s are a generalized abstraction for communication between parts of a program,
whether on the same physical host or distributed over a network. Endpoint
s 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 Endpoint
s with different Transport
s without modifying the logic of their
application that sends / receives Message
s.
- data Endpoint
- newEndpoint :: [Transport] -> IO Endpoint
- bindEndpoint :: Endpoint -> Name -> IO (Either String ())
- unbindEndpoint :: Endpoint -> Name -> IO (Either String ())
- sendMessage :: Endpoint -> Name -> Message -> IO (Either String ())
- broadcastMessage :: Endpoint -> [Name] -> Message -> IO [Either String ()]
- receiveMessage :: Endpoint -> IO Message
- receiveMessageTimeout :: Endpoint -> Int -> IO (Maybe Message)
- module Network.Transport
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")] 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
Primary API
unbindEndpoint :: Endpoint -> Name -> IO (Either String ())Source
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 ())Source
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
.
receiveMessageTimeout :: Endpoint -> Int -> IO (Maybe Message)Source
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 Endpoint
s does not
require direct use of Transport
s, beyond creating specific Transport
s (such as
found in Network.Transport.Memory and Network.Transport.TCP) and adding
them to an Endpoint
.
module Network.Transport