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


-- | A cache system associating values to files.
--   
--   A 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.3.2


-- | Internal module ... use at your own risks!
module Data.FileCache.Internal

-- | The main FileCache type, for queries returning 'Either r a'. The r
--   type must be an instance of <tt>Error</tt>.
data FileCacheR r a
FileCache :: TVar (Map FilePath (Either r a)) -> TVar (Map FilePath (Set FilePath, StopListening)) -> WatchManager -> EventChannel -> TVar (Maybe ThreadId) -> FileCacheR r a
[_cache] :: FileCacheR r a -> TVar (Map FilePath (Either r a))
[_watchedDirs] :: FileCacheR r a -> TVar (Map FilePath (Set FilePath, StopListening))
[_manager] :: FileCacheR r a -> WatchManager
[_channel] :: FileCacheR r a -> EventChannel
[_tid] :: FileCacheR r a -> TVar (Maybe ThreadId)

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

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

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

-- | Manually invalidates an entry.
invalidate :: FilePath -> FileCacheR e a -> IO ()
canon :: FilePath -> IO FilePath

-- | 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.
query :: forall e a. IsString e => FileCacheR e a -> FilePath -> IO (Either e a) -> IO (Either e a)

-- | Just like <a>query</a>, but with the standard <a>Either</a> type. Note
--   that it is just there for easy interoperability with the more comme
--   <a>Either</a> type, as the result is still forced.
lazyQuery :: IsString r => FileCacheR r a -> FilePath -> IO (Either r a) -> IO (Either r a)

-- | Gets a copy of the cache.
getCache :: FileCacheR e a -> IO (Map FilePath (Either e a))


-- | 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. The result is forced to WHNM.
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 <tt>Error</tt>.
data FileCacheR r a

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

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

-- | Manually invalidates an entry.
invalidate :: FilePath -> FileCacheR e 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.
query :: forall e a. IsString e => FileCacheR e a -> FilePath -> IO (Either e a) -> IO (Either e a)

-- | Gets a copy of the cache.
getCache :: FileCacheR e a -> IO (Map FilePath (Either e a))

-- | Just like <a>query</a>, but with the standard <a>Either</a> type. Note
--   that it is just there for easy interoperability with the more comme
--   <a>Either</a> type, as the result is still forced.
lazyQuery :: IsString r => FileCacheR r a -> FilePath -> IO (Either r a) -> IO (Either r a)
