Network.Connection

baseRead :: Int -> IO ByteString	Read, at most, the given number of bytes from the connection and return a ByteString of the data. EOF is signaled by an exception and a zero length string is never a valid return value
baseWrite :: ByteString -> IO Int	Write the given ByteString to the connection. The write may write less than the requested number of bytes (but must always write at least one byte)
baseClose :: IO ()	Close a connection

Connection functions

data Connection

A Connection uses the functions from a BaseConnection and wraps them a number of commonly needed behaviours.

Firstly, a write queue is introduced so that writes can be non-blocking.

Secondly, the Connection can manage a number of threads. Almost always there will be a writer thread which is taking items from the write queue and writing them to the BaseConnection. In addition, there can be zero or more other threads managed by the Connection. If a thread which is managed dies, by throwing an exception or otherwise, it will close the connection and all other managed threads will be killed.

There is also the concept of pushing data back into the Connection. This is useful in a chain of reader functions where, for efficiency reasons, you would want to read large blocks at a time, but the data is self-deliminating so you would otherwise end up in a situation where you had read too much. See the pushBack function for details.

new

:: IO ()	the action to run when the connection closes
-> BaseConnection	the socket-like object to make a connection from
-> IO Connection
Create a new Connection from a BaseConnection object

newSTM

:: IO ()	the action run when the connection closes
-> BaseConnection	the socket-like object to make a connection from
-> STM Connection
This creates most of a Connection, purely in the STM monad. The Connection returned from this must be passed to forkWriterThread, otherwise nothing will ever get written.

forkWriterThread

:: Connection	the connection to fork the writer thread for
-> IO ()
If you created the Connection in the STM monad using newSTM, you need to call this on it in order to create the thread which processes the outgoing queue.

forkInConnection

:: Connection	the connection to close on death
-> IO ()	the action to run
-> IO ()
Run the given action, as if by forkIO, and manage the thread. If the given action completes or throws an exception, the connection will be closed and all other managed threads will be killed

close :: Connection -> IO ()

Close a connection

write :: Connection -> ByteString -> STM ()

Enqueue a ByteString to a connection. This does not block.

writeAtLowWater

:: Int	the max number of bytes in the queue before we enqueue anything
-> Connection	the connection to write to
-> ByteString	the data to enqueue
-> STM ()
Block until the write queue has less than the given number of bytes in it then enqueue a new ByteString.

read :: Connection -> Int -> IO ByteString

Read some number of bytes from a connection. The size is only a hint, the returned data may be shorter. A zero length read is EOF

reada :: Connection -> Int -> IO ByteString

Read exactly a give number of bytes

pushBack :: Connection -> ByteString -> STM ()

Unread some amount of data. It will be returned in the next call to read.

The function pushes data to the front of the queue. Thus you need to push all the data base in one go, or the order of future reads will be wrong.

This might seem like an error, but consider the case of two actions: the first reads 20 bytes and pushs back the last 10 of them. The second reads 5 bytes and pushs back the last 4. If we appended to the push back queue the second action would put those 4 bytes after the remaining 5 from the first action.

Produced by Haddock version 2.0.0.0