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


-- | On-disk storage, but referentially transparent
--   
--   This package provides a data type <a>DiskBytes</a> which represents a
--   sequence of bytes that is stored on disk — but in a referentially
--   transparent manner.
@package disk-bytes
@version 0.1.0.0

module System.Mem.Disk

-- | A sequence of bytes that is stored on disk — if and only if the value
--   is evaluated to WHNF.
--   
--   The value is subject to normal garbage collection: When the value is
--   no longer referenced, the disk memory will be freed (eventually).
--   
--   For estimating the memory cost: Even though the bulk of the data is
--   kept on disk, each WHNF of <a>DiskBytes</a> occupies roughly
--   <tt>~100</tt> bytes of RAM; this is due to administrative overhead
--   like weak pointers and finalizers.
data DiskBytes

-- | Offload a sequence of bytes onto a <a>Disk</a>.
--   
--   NOTE: The result must be evaluated to WHNF before the data is actually
--   on disk! Also, the original <a>ByteString</a> needs to be garbage
--   collected in for its RAM to become free.
toDiskBytes :: Disk -> ByteString -> DiskBytes

-- | Read the sequence of bytes back into RAM.
fromDiskBytes :: DiskBytes -> ByteString

-- | Represents the on-disk storage where <a>DiskBytes</a> are stored.
data Disk

-- | Rough estimate of the current size of the <a>Disk</a>, in bytes.
getDiskSize :: Disk -> IO Integer

-- | Create a new file and use it for storing <a>DiskBytes</a>.
--   
--   Throw an error if the file already exists, delete the file after use.
withDiskSqlite :: FilePath -> (Disk -> IO a) -> IO a

-- | Create a <a>Disk</a> in memory for the purpose of testing and
--   profiling — by swapping <a>withDiskMemory</a> for
--   <a>withDiskSqlite</a> and looking at the heap profile of your program,
--   you can quickly find out whether the use of <a>DiskBytes</a> really
--   helps.
--   
--   Ignores the <a>FilePath</a> argument.
withDiskMemory :: FilePath -> (Disk -> IO a) -> IO a