-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | A client library for the spread toolkit
--   
--   hspread is a client library for the Spread toolkit. It is fully
--   implemented in haskell and supports the most recent version of the
--   protocol. It's intended to be used with a serialization library like
--   binary, and a separate installation of the spread deamon.
@package hspread
@version 0.3


-- | Unbounded closeable channels.
module Control.Concurrent.Chan.Closeable

-- | <a>Chan</a> is an abstract type representing an unbounded FIFO
--   channel.
data Chan t a

-- | <a>R</a> for ReadOnly
data R

-- | <a>W</a> for WriteOnly
data W

-- | Build and returns a pair of <a>Chan</a>, data written on the W end can
--   be read from the R end.
newChan :: IO (Chan R a, Chan W a)

-- | Write a value to a <a>Chan</a>. Returns True if successful, False if
--   the channel is closed.
writeChan :: Chan W a -> a -> IO Bool

-- | Close the <a>Chan</a>, data can be no more written to it. Returns True
--   if the <a>Chan</a> was already closed.
closeChan :: Chan W a -> IO Bool

-- | Non-blocking check.
isClosedChan :: Chan t a -> IO Bool

-- | Read the next value from the <a>Chan</a>. |Nothing if the <a>Chan</a>
--   is closed.
readChan :: Chan R a -> IO (Maybe a)

-- | Forks a <a>Chan</a>: data that will be written (W) or is yet to be
--   read (R) on the argument, will also be available on the returned
--   channel.
forkChan :: Chan t a -> IO (Chan R a)

-- | Put a data item back onto a channel, where it will be the next item
--   read.
unGetChan :: Chan R a -> a -> IO ()

-- | Returns <a>True</a> if the supplied <a>Chan</a> is empty, i.e.
--   readChan won't block.
isEmptyChan :: Chan R a -> IO Bool

-- | Return a lazy list representing the contents of the supplied
--   <a>Chan</a>, much like <tt>System.IO.hGetContents</tt>.
getChanContents :: Chan R a -> IO [a]

-- | Write an entire list of items to a <a>Chan</a>. Returning the
--   remainder if the channel has been closed meanwhile.
writeList2Chan :: Chan W a -> [a] -> IO (Maybe [a])

module Spread.Client

-- | Message to be sent.
data OutMsg
Outgoing :: !OrderingType -> !Bool -> !ByteString -> ![Group] -> !Word16 -> OutMsg
outOrdering :: OutMsg -> !OrderingType

-- | If True you won't get a copy of this message back from the server.
outDiscard :: OutMsg -> !Bool

-- | Message body.
outData :: OutMsg -> !ByteString

-- | Recipients of the message
outGroups :: OutMsg -> ![Group]

-- | To be used by the application to identify the kind of message.
outMsgType :: OutMsg -> !Word16

-- | Message received.
data InMsg
Incoming :: !OrderingType -> !PrivateGroup -> !ByteString -> ![Group] -> !Word16 -> !Bool -> InMsg
inOrdering :: InMsg -> !OrderingType
inSender :: InMsg -> !PrivateGroup
inData :: InMsg -> !ByteString
inGroups :: InMsg -> ![Group]
inMsgType :: InMsg -> !Word16

-- | True if the message has been sent with a different endian order.
inEndianMismatch :: InMsg -> !Bool

-- | Union Type of messages that can be received from the server.
data Message
Regular :: !InMsg -> Message
Membership :: !MembershipMsg -> Message
Rejected :: !RejectedMsg -> Message

-- | A <a>Group</a> is a collection of clients identified by a name.
data Group

-- | A <a>PrivateGroup</a> identifies a connection.
type PrivateGroup = Group

-- | Initial part of a <a>PrivateGroup</a> name that is chosen by the
--   client when connecting.
data PrivateName

-- | Identifier for a membership message.
data GroupId

-- | Represents the orderings as specified by the Spread toolkit.
data OrderingType
Unreliable :: OrderingType
Reliable :: OrderingType
Fifo :: OrderingType
Causal :: OrderingType
Agreed :: OrderingType
Safe :: OrderingType

-- | What caused a membership message.
data Cause
Join :: !PrivateGroup -> Cause
joining :: Cause -> !PrivateGroup
Leave :: !PrivateGroup -> Cause
leaving :: Cause -> !PrivateGroup
Disconnect :: !PrivateGroup -> Cause
disconnecting :: Cause -> !PrivateGroup
Network :: ![[PrivateGroup]] -> ![PrivateGroup] -> Cause
sets :: Cause -> ![[PrivateGroup]]
localSet :: Cause -> ![PrivateGroup]
groupName :: Group -> ByteString
mkPrivateGroup :: ByteString -> Group
privateName :: PrivateName -> ByteString

-- | Messages used to join or leave a group.
data GroupMsg
Joining :: !Group -> GroupMsg
grp :: GroupMsg -> !Group
Leaving :: !Group -> GroupMsg
grp :: GroupMsg -> !Group

-- | Message regarding changes in group membership.
data MembershipMsg
Transient :: !Group -> MembershipMsg
changingGroup :: MembershipMsg -> !Group
Reg :: !Group -> !Int -> !Int -> ![PrivateGroup] -> !GroupId -> !Cause -> MembershipMsg
changingGroup :: MembershipMsg -> !Group
index :: MembershipMsg -> !Int
numMembers :: MembershipMsg -> !Int
members :: MembershipMsg -> ![PrivateGroup]
groupId :: MembershipMsg -> !GroupId
cause :: MembershipMsg -> !Cause
SelfLeave :: !Group -> MembershipMsg
changingGroup :: MembershipMsg -> !Group
receive_internal :: Handle -> PrivateGroup -> IO Message
multicast_internal :: (Sendable a) => PrivateGroup -> a -> Handle -> IO Bool
mkGroup :: ByteString -> Maybe Group
mkPrivateName :: ByteString -> PrivateName
putPadded :: Int -> ByteString -> PutM ()
makeGroup :: String -> Maybe Group
data KillMsg
Kill :: PrivateGroup -> KillMsg
data RejectedMsg
WasGroup :: !GroupMsg -> RejectedMsg
WasOut :: !OutMsg -> RejectedMsg

-- | Abstract type representing a connection with a spread server.
data Connection

-- | private name of this connection, useful for p2p messages.
privateGroup :: Connection -> PrivateGroup

-- | Configuration passed to <a>connect</a>
data Conf
Conf :: !Maybe HostName -> !Maybe PortNumber -> !PrivateName -> !Bool -> !Bool -> ![AuthMethod] -> Conf

-- | Server address, using localhost if <a>Nothing</a>.
address :: Conf -> !Maybe HostName

-- | Server port, uses the default spread port if <a>Nothing</a>.
port :: Conf -> !Maybe PortNumber

-- | It will become part of the <a>PrivateGroup</a> of the
--   <a>Connection</a>
desiredName :: Conf -> !PrivateName

-- | Is this a priority connection?
priority :: Conf -> !Bool

-- | Should it receive Membership messages?
groupMembership :: Conf -> !Bool

-- | Authentication methods to use when connecting.
authMethods :: Conf -> ![AuthMethod]

-- | defaulConf = Conf Nothing Nothing (mkPrivateName (B.pack "user"))
--   False True []
defaultConf :: Conf

-- | Name of an authentication method.
data AuthName

-- | The <a>ByteString</a> will be truncated to the maximum allowed size.
mkAuthName :: ByteString -> AuthName
authname :: AuthName -> ByteString

-- | The action should return True if the authentication succeded.
type AuthMethod = (AuthName, Handle -> IO Bool)

-- | Connects to the specified server, will use a "NULL" authentication
--   method if the <a>authMethods</a> list is empty. A spread server will
--   refuse the connection if another with the same PrivateName is still
--   active.
connect :: Conf -> IO (Chan R Message, Connection)

-- | Sends a disconnection message to the server, which will close the
--   connection.
disconnect :: Connection -> IO ()

-- | Start fetching messages from the network, returns True if it was
--   stopped.
startReceive :: Connection -> IO Bool

-- | Stop fetching messages from the network (at most one more message can
--   be read) , returns True if it was started.
stopReceive :: Connection -> IO Bool

-- | Messages received from now on will be available on the returned
--   <a>Chan</a>
getDupedChan :: Connection -> IO (Chan R Message)

-- | Joins a group, the server will send a <a>Reg</a>.
join :: Group -> Connection -> IO ()

-- | Leaves a group, the server will send a <a>SelfLeave</a>.
leave :: Group -> Connection -> IO ()

-- | Send a regular message.
send :: OutMsg -> Connection -> IO ()