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


-- | A Linux-only cache system associating values to files.
--   
--   A Linux-only cache system, that works by associating computation
--   results with file names. When the files are modified, the cache
--   entries are discarded.
@package filecache
@version 0.2.3


-- | This module let you create caches where keys are file names, and
--   values are automatically expired when the file is modified for any
--   reason.
--   
--   This is usually done in the following fashion :
--   
--   <pre>
--   cache &lt;- newFileCache
--   o &lt;- query cache "/path/to/file" computation
--   </pre>
--   
--   The computation will be used to populate the cache if this call
--   results in a miss.
module Data.FileCache

-- | A default type synonym, for String errors.
type FileCache = FileCacheR String

-- | The main FileCache type, for queries returning 'Either r a'. The r
--   type must be an instance of <a>Error</a>.
data FileCacheR r a

-- | Generates a new file cache. The opaque type is for use with other
--   functions.
newFileCache :: Error r => IO (FileCacheR r a)

-- | Destroys the thread running the FileCache. Pretty dangerous stuff.
killFileCache :: FileCacheR r a -> IO ()

-- | Manually invalidates an entry.
invalidate :: Error r => FilePath -> FileCacheR r a -> IO ()

-- | Queries the cache, populating it if necessary, returning a strict
--   <a>Either</a> (from <a>Data.Either.Strict</a>).
--   
--   Queries that fail with an <tt>IOExeception</tt> will not create a
--   cache entry. Also please note that there is a race condition between
--   the potential execution of the computation and the establishment of
--   the watch.
query :: Error r => FileCacheR r a -> FilePath -> IO (Either r a) -> IO (Either r a)

-- | Gets a copy of the cache.
getCache :: Error r => FileCacheR r a -> IO (HashMap FilePath (Either r a, WatchDescriptor))

-- | Just like <a>query</a>, but with the standard <a>Either</a> type.
lazyQuery :: Error r => FileCacheR r a -> FilePath -> IO (Either r a) -> IO (Either r a)