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


-- | Disk-based hash table
--   
--   Disk-based hash table
@package diskhash
@version 0.0.3.2


-- | Disk based hash table
--   
--   The Haskell interface has two types, distinguishing between read-only
--   and read-write hash tables. Operations on the RW variant are in the IO
--   monad, while operations on RO tables are all pure (after the
--   <a>htOpenRO</a> call, naturally). Using read-write hashtables with
--   more than one thread is undefined behaviour, but the read-only variant
--   is perfectly thread safe.
--   
--   All data structures are strict (naturally: they write to disk).
--   
--   The Haskell API can be used to access diskhashes created from other
--   languages as long as the types are compatible.
module Data.DiskHash

-- | Represents a read-only diskhash storing type <tt>a</tt>
data DiskHashRO a

-- | Represents a read-write diskhash storing type <tt>a</tt>
data DiskHashRW a

-- | open a hash table in read-only mode
--   
--   The <tt>maxk</tt> argument can be 0, in which case the value of the
--   maximum key will be taken from the disk file. If not zero, then it is
--   checked against the value on disk and an exception is raised if there
--   is a mismatch.
htOpenRO :: forall a. (Storable a) => FilePath -> Int -> IO (DiskHashRO a)

-- | open a hash table in read-write mode
htOpenRW :: forall a. (Storable a) => FilePath -> Int -> IO (DiskHashRW a)

-- | Open a hash table in read-write mode and pass it to an action
--   
--   Once the action is is complete, the hashtable is closed (and sync'ed
--   to disk).
withDiskHashRW :: (Storable a) => FilePath -> Int -> (DiskHashRW a -> IO b) -> IO b

-- | Lookup by key
--   
--   This is a pure operation
htLookupRO :: (Storable a) => ByteString -> DiskHashRO a -> Maybe a

-- | Lookup by key
--   
--   This is in the IO Monad to ensure ordering of operations.
htLookupRW :: (Storable a) => ByteString -> DiskHashRW a -> IO (Maybe a)

-- | Retrieve the size of the hash table
htSizeRW :: DiskHashRW a -> IO Int

-- | Retrieve the size of the hash table
htSizeRO :: DiskHashRO a -> Int

-- | insert an element into the hash table
--   
--   Returns whether an insertion took place (if an object with that key
--   already exists, no insertion is made).
--   
--   This operation can fail (throwing an exception) if space could not be
--   allocated. You can pre-allocate space using <a>htReserve</a>.
htInsert :: (Storable a) => ByteString -> a -> DiskHashRW a -> IO Bool

-- | Modify a value
htModify :: (Storable a) => ByteString -> (a -> a) -> DiskHashRW a -> IO Bool

-- | Reserve space in the hash table
--   
--   Reserving space can ensure that any subsequent <a>htInsert</a> calls
--   will not fail.
--   
--   If the operation fails, an exception is raised
htReserve :: (Storable a) => Int -> DiskHashRW a -> IO Int