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


-- | Mutable vector with different GC characteristics
--   
--   Library for avoiding excessive mutable array traversals by the garbage
--   collector when you use compact regions for your elements.
--   
--   See Haddock for more information.
@package compact-mutable-vector
@version 0.0.0.1


-- | When you use normal mutable vectors, the garbage collector will
--   traverse them on every garbage collection, because they may point to
--   data that is newer than them. If you want to store your elements on a
--   compact region anyway, but also need to point to them from a mutable
--   vector, you can exploit the stability of the elements' addresses after
--   adding them to the compact region, to avoid these expensive traversals
--   when collecting garbage.
--   
--   This library offers a data type for mutable vectors where all elements
--   are stored in a compact region, using an unspeakable pointer casting
--   hack.
module Data.Vector.Mutable.Compact

-- | Store the elements of the vector in a compact region, and use an
--   unboxed vector of pointers to the elements. Values in a compact region
--   will not be moved by the garbage collector, so their addresses are
--   stable, and can hence be stored in a mutable byte array. This avoids
--   garbage collection overhead if you store your elements in a compact
--   region anyway, because the garbage collector will not traverse byte
--   arrays.
--   
--   The elements must be able to be stored in a compact region. See
--   <a>Data.Compact</a> for a list of restrictions. The vector itself
--   cannot itself be stored in a compact region, because it is mutable.
--   
--   Elements can never be bottom, because they are added to a compact
--   region.
data CVector a

-- | Create a new mutable vector of the given length, with each element set
--   to the given value. The given compact region will be used for all
--   future elements inserted into this vector.
replicate :: Compact () -> Int -> b -> IO (CVector b)

-- | Read the element at the given zero-based position. If the position is
--   out of bounds, crash.
read :: CVector a -> Int -> IO a

-- | Write an element at the given zero-based position. If the position is
--   out of bounds, crash.
--   
--   The element will be added to the compact region.
write :: CVector a -> Int -> a -> IO ()

-- | How many elements are in the vector?
length :: CVector a -> Int

-- | Is the vector empty?
null :: CVector a -> Bool