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


-- | A concurrent, mutable ring-buffer
--   
--   A mutable ring-buffer implementation suitable for concurrent access.
@package ring-buffer
@version 0.4


-- | This is a thread-safe implementation of a mutable ring-buffer built
--   upon <tt>vector</tt>.
module Data.RingBuffer

-- | A concurrent ring buffer.
data RingBuffer v a

-- | Create a new ring of a given length
--   
--   <i>Note:</i> size must be non-zero
new :: (Vector v a) => Int -> IO (RingBuffer v a)

-- | Reset the ringbuffer to its empty state
clear :: Vector v a => RingBuffer v a -> IO ()

-- | Add an item to the end of the ring
append :: (Vector v a) => a -> RingBuffer v a -> IO ()

-- | Add multiple items to the end of the ring This ignores any items above
--   the length of the ring
concat :: (Vector v a) => v a -> RingBuffer v a -> IO ()

-- | The maximum number of items the ring can contain
capacity :: (Vector v a) => RingBuffer v a -> Int

-- | The current filled length of the ring
length :: (Vector v a) => RingBuffer v a -> IO Int

-- | Retrieve the &lt;math&gt;th most-recently added item of the ring
latest :: (Vector v a) => RingBuffer v a -> Int -> IO (Maybe a)

-- | Get the entire contents of the ring, with the most recently added
--   element at the head. Note that this is rather inefficient.
toList :: (Vector v a) => RingBuffer v a -> IO [a]

-- | Execute the given action with the items of the ring. Note that no
--   references to the vector may leak out of the action as it will later
--   be mutated. Moreover, the items in the vector are in no particular
--   order.
withItems :: (MonadIO m, MonadMask m, Vector v a) => RingBuffer v a -> (v a -> m b) -> m b