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


-- | Efficiently build a bytestring from smaller chunks
--   
--   Efficiently (both fast and memory efficient) build a bytestring from
--   smaller chunks
@package superbuffer
@version 0.3.1.1

module Data.ByteString.SuperBuffer.Pure

-- | The buffer data structure.
data SuperBuffer

-- | Allocate a new buffer with a given initial size. The perfect starting
--   point depends on the expected total size and the average size for a
--   single chunk written with <a>appendBuffer</a>. You can always start
--   with 1024 and optimize from there with benchmarks. Please note that
--   the SuperBuffer will no longer be valid after this function
--   terminates, so do NOT pass it to some other thread without waiting for
--   it to finish in the action.
withBuffer :: Int -> (SuperBuffer -> IO ()) -> IO ByteString

-- | Write a bytestring to the buffer and grow the buffer if needed. Note
--   that only one thread at any given time may call this function. Use
--   <a>appendBufferT</a> when accessing <a>SuperBuffer</a> from multiple
--   threads.
appendBuffer :: SuperBuffer -> ByteString -> IO ()

-- | Write a bytestring to the buffer and grow the buffer if needed. This
--   function can be used accross different threads, but is slower than
--   <a>appendBuffer</a>.
appendBufferT :: SuperBuffer -> ByteString -> IO ()

-- | Get current (filled) size of the buffer
size :: SuperBuffer -> IO Int

module Data.ByteString.SuperBuffer

-- | The buffer. Internally only a pointer to a C struct. Don't worry, this
--   module attempts to make usage of the SuperBuffer as safe as possible
--   in terms of memory leaks (even when exceptions occur).
data SuperBuffer

-- | Allocate a new buffer with a given initial size. The perfect starting
--   point depends on the expected total size and the average size for a
--   single chunk written with <a>appendBuffer</a>. You can always start
--   with 1024 and optimize from there with benchmarks. Please note that
--   the SuperBuffer will no longer be valid after this function
--   terminates, so do NOT pass it to some other thread without waiting for
--   it to finish in the action.
withBuffer :: Int64 -> (SuperBuffer -> IO ()) -> IO ByteString

-- | Write a bytestring to the buffer and grow the buffer if needed. Note
--   that only one thread at any given time may call this function. Use
--   <a>appendBufferT</a> when accessing <a>SuperBuffer</a> from multiple
--   threads.
appendBuffer :: SuperBuffer -> ByteString -> IO ()

-- | Write a bytestring to the buffer and grow the buffer if needed. This
--   function can be used accross different threads, but is slower than
--   <a>appendBuffer</a>.
appendBufferT :: SuperBuffer -> ByteString -> IO ()

-- | Get current (filled) size of the buffer
size :: SuperBuffer -> IO Int
