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


-- | Short description
--   
--   Lock-free threadsafe pinned memory pool manager
@package memory-pool
@version 0.1.0.0


-- | The goal of this Memory Pool is to provide the ability to allocate big
--   chunks of memory that can fit many <a>Block</a>s. Some memory
--   allocators out there have a fairly large minimal size requirement,
--   which would be wasteful if many chunks of small size (eg. 32 bytes)
--   are needed at once. Memory pool will allocate one page at a time as
--   more blocks is needed.
--   
--   Currently there is no functionality for releasing unused pages. So,
--   once a page is allocated, it will be re-used when more <a>Block</a>s
--   is needed, but it will not be GCed until the whole <a>Pool</a> is
--   GCed.
module System.Memory.Pool

-- | Thread-safe lock-free memory pool for managing large memory pages that
--   are made up of many small <a>Block</a>s.
data Pool n s

-- | Initilizes the <a>Pool</a> that can be used for further allocation of
--   <tt><a>ForeignPtr</a> <a>Block</a> n</tt> with <a>grabNextBlock</a>.
initPool :: forall n s. KnownNat n => Int -> (forall a. Int -> ST s (ForeignPtr a)) -> (Ptr (Block n) -> IO ()) -> ST s (Pool n s)

-- | This is just a proxy type that carries information at the type level
--   about the size of the block in bytes supported by a particular
--   instance of a <a>Pool</a>. Use <a>blockByteCount</a> to get the byte
--   size at the value level.
data Block (n :: Nat)
Block :: Block (n :: Nat)

-- | Number of bytes in a <a>Block</a>
blockByteCount :: KnownNat n => Block n -> Int

-- | Reserve a <a>ForeignPtr</a> of the <a>blockByteCount</a> size in the
--   <a>Pool</a>. There is a default finalizer attached to the
--   <a>ForeignPtr</a> that will run <a>Block</a> pointer finalizer and
--   release that memory for re-use by other blocks allocated in the
--   future. It is safe to add more Haskell finalizers with
--   <a>addForeignPtrConcFinalizer</a> if necessary.
grabNextBlock :: KnownNat n => Pool n s -> ST s (ForeignPtr (Block n))

-- | Useful function for testing. Check how many pages have been allocated
--   thus far.
countPages :: Pool n s -> ST s Int

-- | Helper function that finds an index of the left-most bit that is not
--   set.
findNextZeroIndex :: forall b. FiniteBits b => b -> Maybe Int