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

-- | Efficient network recv
--   
--   Network recv based on buffer pools
@package recv
@version 0.1.1

-- | This module provides efficient receiving functions from the network.
--   recv uses createAndTrim which behaves as follows:
--   
--   
--   
- Allocates a buffer whose size is decided from the first
--   argument.
--   
- Receives data with the buffer.
--   
- Allocates another buffer whose size fits the received data.
--   
- Copies the data from the first buffer to the second buffer.
--   
--   
--   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 recv 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 pool 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 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.
--   
--   
--   >>> :seti -XOverloadedStrings
--   
--   >>> tryRecvN "a" 3 =<< _iorefRecv ["bcd"]
--   ("abc","d")
--   
--   >>> tryRecvN "a" 3 =<< _iorefRecv ["bc"]
--   ("abc","")
--   
--   >>> tryRecvN "a" 3 =<< _iorefRecv ["b"]
--   ("ab","")
--   
makeRecvN :: ByteString -> Recv -> 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
