Copyright | (c) Erick Gonzalez 2019 |
---|---|
License | BSD3 |
Maintainer | erick@codemonkeylabs.de |
Safe Haskell | None |
Language | Haskell2010 |
This library extends fast mutable hashtables so that entries added can be expired after a given TTL (time to live). This TTL can be specified as a default property of the table or on a per entry basis.
Synopsis
- data TTLHashTable h k v
- data TTLHashTableError
- data Settings = Settings {
- maxSize :: Int
- renewUponRead :: Bool
- defaultTTL :: Int
- insert :: (Eq k, Hashable k, HashTable h, MonadIO m, Failable m) => TTLHashTable h k v -> k -> v -> m ()
- insert_ :: (Eq k, Hashable k, HashTable h, MonadIO m) => TTLHashTable h k v -> k -> v -> m ()
- insertWithTTL :: (Eq k, Hashable k, HashTable h, MonadIO m, Failable m) => TTLHashTable h k v -> Int -> k -> v -> m ()
- insertWithTTL_ :: (Eq k, Hashable k, HashTable h, MonadIO m) => TTLHashTable h k v -> Int -> k -> v -> m ()
- delete :: (HashTable h, Eq k, Hashable k, MonadIO m) => TTLHashTable h k v -> k -> m ()
- find :: (Eq k, Hashable k, MonadIO m) => TTLHashTable h k v -> k -> m (Maybe v)
- lookup :: (Eq k, Hashable k, MonadIO m, Failable m) => TTLHashTable h k v -> k -> m v
- new :: (HashTable h, MonadIO m) => m (TTLHashTable h k v)
- newWithSettings :: (HashTable h, MonadIO m) => Settings -> m (TTLHashTable h k v)
- removeExpired :: (MonadIO m, Eq k, Hashable k) => TTLHashTable h k v -> m ()
- size :: MonadIO m => TTLHashTable h k v -> m Int
How to use this module:
Import one of the hash table modules from the hashtables package.. i.e. Basic, Cuckoo, etc and "wrap" them in a TTLHashTable:
import Data.HashTable.ST.Basic as Basic type HashTable k v = TTLHashTable Basic.HashTable k v
You can then use the functions in this module with this hashtable type. Note that the
functions in this module which can fail offer a flexible error handling strategy by virtue of
working in the context of a Failable
monad. So for example, if the function is used directly
in the IO monad and a failure occurs it would then result in an exception being thrown. However
if the context supports the possibiliy of failure like a MaybeT
or ExceptT
transformer, it would then instead return something like IO Nothing
or Left NotFound
respectively (depending on the actual failure of course).
None of the functions in this module are thread safe, just as the underlying mutable hash tables in the ST monad aren't as well. If concurrent threads need to operate on the same table, you need to provide external means of synchronization to guarantee exclusive access to the table
data TTLHashTable h k v Source #
The TTL hash table type, parameterized on the type of table, key and value.
data TTLHashTableError Source #
Exception type used to report failures (depending on calling context)
NotFound | The entry was not found in the table |
ExpiredEntry | The entry did exist but is no longer valid |
HashTableFull | The maximum size for the table has been reached |
Instances
Eq TTLHashTableError Source # | |
Defined in Data.TTLHashTable (==) :: TTLHashTableError -> TTLHashTableError -> Bool # (/=) :: TTLHashTableError -> TTLHashTableError -> Bool # | |
Show TTLHashTableError Source # | |
Defined in Data.TTLHashTable showsPrec :: Int -> TTLHashTableError -> ShowS # show :: TTLHashTableError -> String # showList :: [TTLHashTableError] -> ShowS # | |
Exception TTLHashTableError Source # | |
Defined in Data.TTLHashTable |
The Settings
type allows for specifying how the hash table should behave.
Settings | |
|
insert :: (Eq k, Hashable k, HashTable h, MonadIO m, Failable m) => TTLHashTable h k v -> k -> v -> m () Source #
Insert a new entry into the hash table. Take note of the fact that this function can fail
for example if table has reached maxSize entries for example. Failure is signaled depending on
the calling Failable
context. So for example if called in pure IO, it would throw a regular
IO exception (of type TTLHashTableError
). For this reason,
you probably want to call this function in a MaybeT
or ExceptT
monad
insert_ :: (Eq k, Hashable k, HashTable h, MonadIO m) => TTLHashTable h k v -> k -> v -> m () Source #
insertWithTTL :: (Eq k, Hashable k, HashTable h, MonadIO m, Failable m) => TTLHashTable h k v -> Int -> k -> v -> m () Source #
like insert
but an entry specific TTL can be provided
insertWithTTL_ :: (Eq k, Hashable k, HashTable h, MonadIO m) => TTLHashTable h k v -> Int -> k -> v -> m () Source #
like insertWithTTL
but ignores insertion failure
delete :: (HashTable h, Eq k, Hashable k, MonadIO m) => TTLHashTable h k v -> k -> m () Source #
delete an entry from the hash table.
lookup :: (Eq k, Hashable k, MonadIO m, Failable m) => TTLHashTable h k v -> k -> m v Source #
Lookup a key in the hash table. If called straight in the IO monad it would throw a
NotFound
exception, but if called under MaybeT IO
or ExceptT SomeException IO
it would
return IO Nothing
or IO (Left NotFound)
respectively. So you probably want to
execute this function in one of these transformer monads
new :: (HashTable h, MonadIO m) => m (TTLHashTable h k v) Source #
Creates a new hash table with default settings
newWithSettings :: (HashTable h, MonadIO m) => Settings -> m (TTLHashTable h k v) Source #
removeExpired :: (MonadIO m, Eq k, Hashable k) => TTLHashTable h k v -> m () Source #
Run garbage collection of expired entries in the table. Note that this function as well as all other operations in a hash table are not thread safe. If concurrent threads need to operate on the table, some concurrency primitive must be used to guarantee exclusive access.