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


-- | Efficient netowrk recv
--   
--   Network recv based on buffer pools
@package recv
@version 0.0.0


-- | This module provides efficient receiving functions from the network.
--   <a>recv</a> uses <tt>createAndTrim</tt> which behaves as follows:
--   
--   <ul>
--   <li>Allocates a buffer whose size is decided from the first
--   argument.</li>
--   <li>Receives data with the buffer.</li>
--   <li>Allocates another buffer whose size fits the received data.</li>
--   <li>Copies the data from the first buffer to the second buffer.</li>
--   </ul>
--   
--   On 64bit machines, the global lock is taken for the allocation of a
--   byte string whose length is larger than or equal to 3272 bytes. So,
--   for instance, if 4,096 is specified to <tt>recv</tt> and the size of
--   received data is 3,300, the global lock is taken twice with the copy
--   overhead.
--   
--   The efficient receiving functions provided here use a buffer pool. A
--   large buffer is allocated at the beginning and it is divided into a
--   used one and a leftover when receiving. The latter is kept in the
--   buffer pooll and will be used next time. When the buffer gets small
--   and usefless, a new large buffer is allocated.
module Network.Socket.BufferPool

-- | Type for the receiving function with a buffer pool.
type Recv = IO ByteString

-- | The receiving function with a buffer pool. The buffer pool is
--   automatically managed.
receive :: Socket -> BufferPool -> Recv

-- | Type for read buffer pool.
data BufferPool

-- | Creating a buffer pool. The first argument is the lower limit. When
--   the size of the buffer in the poll is lower than this limit, the
--   buffer is thrown awany (and is eventually freed). Then a new buffer is
--   allocated. The second argument is the size for the new allocation.
newBufferPool :: Int -> Int -> IO BufferPool

-- | Using a buffer pool. The second argument is a function which returns
--   how many bytes are filled in the buffer. The buffer in the buffer pool
--   is automatically managed.
withBufferPool :: BufferPool -> (Buffer -> BufSize -> IO Int) -> IO ByteString

-- | Type for the receiving function with a buffer. The result boolean
--   indicates whether or not the buffer is fully filled.
type RecvBuf = Buffer -> BufSize -> IO Bool

-- | The receiving function with a buffer. This tries to fill the buffer.
--   This returns when the buffer is filled or reaches EOF.
receiveBuf :: Socket -> RecvBuf

-- | Type for the receiving function which receives N bytes.
type RecvN = Int -> IO ByteString

-- | This function returns a receiving function based on two receiving
--   functions. The returned function receives exactly N bytes. The first
--   argument is an initial received data. After consuming the initial
--   data, the two functions is used. When N is less than equal to 4096,
--   the buffer pool is used. Otherwise, a new buffer is allocated. In this
--   case, the global lock is taken.
makeReceiveN :: ByteString -> Recv -> RecvBuf -> IO RecvN

-- | This function returns a receiving function with two receiving
--   functions is created internally. The second argument is the lower
--   limit of the buffer pool. The third argument is the size of the
--   allocated buffer in the pool. The fourth argument is an initial
--   received data. The returned function behaves as described in
--   <a>makeReceiveN</a>.
makePlainReceiveN :: Socket -> Int -> Int -> ByteString -> IO RecvN

-- | Type for buffer.
type Buffer = Ptr Word8

-- | Type for buffer size.
type BufSize = Int

-- | Allocating a byte string.
mallocBS :: Int -> IO ByteString

-- | Copying the bytestring to the buffer. This function returns the point
--   where the next copy should start.
copy :: Buffer -> ByteString -> IO Buffer