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


-- | A Transactional data cache with configurable persistence
--   
--   Data.Tcache is a transactional cache with configurable persistence. It
--   tries to simulate Hibernate for Java or Rails for Ruby. The main
--   difference is that transactions are done in memory trough STM. There
--   are transactional cache implementations for some J2EE servers like
--   JBOSS.
--   
--   TCache uses STM. It can atomically apply a function to a list of
--   cached objects. The resulting objects go back to the cache
--   (withResources). It also can retrieve these objects (getResources).
--   Persistence can be syncronous (syncCache) or asyncronous, wtih
--   configurable time between cache writes and configurable cache
--   clearance strategy. the size of the cache can be configured too . All
--   of this can be done trough clearSyncCacheProc. Even the TVar variables
--   can be accessed directly (getTVar) to acceess all the semantic of
--   atomic blocks while maintaining the persistence of the TVar updates.
--   
--   Persistence can be defined for each object: Each object must have a
--   defined key, a default filename path (if applicable). Persistence is
--   pre-defined in files, but the readResource writeResource and
--   delResource methods can be redefined to persist in databases or
--   whatever.
--   
--   Serialization is also configurable.
--   
--   There are Samples here that explain the main features.
--   
--   In this release
--   
--   <ul>
--   <li>added withSTMResources. Most of the rest of the methods are
--   derived from withSTMResources . the results are returned in the STM
--   monad, so this method can be part of al larger STM transaction It also
--   can perforn used defined retries.</li>
--   <li>added modules for cached TMVars Data.TCache.TMVar and
--   Data.TCache.TMVar.Dynamic uses TMVars instead of TVars (See
--   Control.Concurrent.STM.TMVar)</li>
--   </ul>
--   
--   It is not possible tu mix TVars and TMVars packages in the same
--   executable. However code that uses dynamic and non dynamic can can be
--   mixed
--   
--   <ul>
--   <li>Data.TCache - cached TVars of object of type a.</li>
--   <li>Data.TCache.Dynamic - cached TVars of objects of type
--   IDynamic.</li>
--   <li>Data.TCache.TMVar - cached TMVars of objects of type a.</li>
--   <li>Data.TCache..TMVar.Dynamic - cached TMVars of objects of type
--   IDynamic.</li>
--   </ul>
@package TCache
@version 0.6.5

module Data.TCache.IResource

-- | Interface that must be defined for every object being cached.
--   <a>readResource</a> and <a>writeResource</a> are implemented by
--   default as read-write to files with its key as filename
--   <a>serialize</a> and <a>deserialize</a> are specified just to allow
--   these defaults. If you define your own persistence, then
--   <tt>serialize</tt> and <tt>deserialize</tt> are not needed. The
--   package <tt>Workflow</tt> need them anyway.
--   
--   minimal definition: keyResource, serialize, deserialize
--   
--   While serialize and deserialize are agnostic about the way of
--   converison to strings, either binary or textual, treadp and tshowp use
--   the monad defined in the RefSerialize package. Both ways of
--   serialization are alternative. one is defined by default in terms of
--   the other. the RefSerialize monad has been introduced to permit
--   IResource objects to be serialized as part of larger structures that
--   embody them. This is necessary for the Workdlow package.
--   
--   The keyResource string must be a unique since this is used to index it
--   in the hash table. when accessing a resource, the user must provide a
--   partial object for wich the key can be obtained. for example:
--   
--   <pre>
--   data Person= Person{name, surname:: String, account :: Int ....)
--   
--   keyResource Person n s ...= n++s
--   </pre>
--   
--   the data being accesed must have the fields used by keyResource
--   filled. For example
--   
--   <pre>
--   readResource Person {name=<a>John</a>, surname= <a>Adams</a>}
--   </pre>
--   
--   leaving the rest of the fields undefined
--   
--   IResource has defaults definitions for all the methods except
--   keyResource Either one or other serializer must be defiened for
--   default witeResource, readResource and delResource
class IResource a
keyResource :: (IResource a) => a -> String
serialize :: (IResource a) => a -> String
deserialize :: (IResource a) => String -> a
tshowp :: (IResource a) => a -> ST String
treadp :: (IResource a) => ST a
defPath :: (IResource a) => a -> String
readResource :: (IResource a) => a -> IO (Maybe a)
writeResource :: (IResource a) => a -> IO ()
delResource :: (IResource a) => a -> IO ()
type AccessTime = Integer
type ModifTime = Integer

-- | Resources returned by <tt>withSTMResources'</tt>
data Resources a b

-- | forces a retry
Retry :: Resources a b
Resources :: [a] -> [a] -> b -> Resources a b

-- | resources to be inserted back in the cache
toAdd :: Resources a b -> [a]

-- | resources to be deleted from the cache and from permanent storage
toDelete :: Resources a b -> [a]

-- | result to be returned
toReturn :: Resources a b -> b

-- | <pre>
--   resources= Resources  [] [] ()
--   </pre>
resources :: Resources a ()


-- | IDynamic is a indexable and serializable version of Dynamic. (See
--   <tt>Data.Dynamic</tt>). It is used as containers of objects in the
--   cache so any new datatype can be incrementally stored without
--   recompilation. IDimamic provices methods for safe casting, besides
--   serializaton, deserialization, registrations and retrieval by lkey.
--   
--   <pre>
--   data IDynamic= forall a. (Typeable a, IResource a) =&gt; IDynamic  a deriving Typeable
--   </pre>
module Data.TCache.IDynamic
data IDynamic
IDynamic :: a -> IDynamic
list :: MVar (Map Word (IDynamic -> IO (Maybe IDynamic), String -> IDynamic, ST IDynamic))

-- | DynamicInterface groups a set of default method calls to handle
--   dynamic objects. It is not necessary to derive instances from it
class DynamicInterface x
toIDyn :: (DynamicInterface x) => x -> IDynamic
registerType :: (DynamicInterface x) => IO x
fromIDyn :: (DynamicInterface x) => IDynamic -> x
unsafeFromIDyn :: (DynamicInterface x) => IDynamic -> x
safeFromIDyn :: (DynamicInterface x) => IDynamic -> Maybe x

-- | Key datatype can be used to read any object trough the Dynamic
--   interface.
--   
--   <pre>
--   data Key =  Key <a>TypeRep</a> String deriving Typeable
--   </pre>
--   
--   Example
--   
--   <pre>
--   mst &lt;- <tt>getDResource</tt> $ <a>Key</a> type <tt>keyofDesiredObject</tt>
--              case mst of
--                Nothing -&gt; error $ "not found "++ key
--                Just (idyn) -&gt;  fromIDyn idyn :: DesiredDatatype}
--   </pre>
data Key
Key :: TypeRep -> String -> Key
instance Typeable Key
instance Typeable IDynamic
instance IResource Key
instance (IResource x, Typeable x) => DynamicInterface x
instance Show IDynamic
instance IResource IDynamic


-- | A version of <tt>Data.TCache</tt> using <tt>TMVar</tt>s instead of
--   <tt>TVars</tt>s. See <tt>Control.Concurrent.TMVar</tt>
module Data.TCache.TMVar

-- | Interface that must be defined for every object being cached.
--   <a>readResource</a> and <a>writeResource</a> are implemented by
--   default as read-write to files with its key as filename
--   <a>serialize</a> and <a>deserialize</a> are specified just to allow
--   these defaults. If you define your own persistence, then
--   <tt>serialize</tt> and <tt>deserialize</tt> are not needed. The
--   package <tt>Workflow</tt> need them anyway.
--   
--   minimal definition: keyResource, serialize, deserialize
--   
--   While serialize and deserialize are agnostic about the way of
--   converison to strings, either binary or textual, treadp and tshowp use
--   the monad defined in the RefSerialize package. Both ways of
--   serialization are alternative. one is defined by default in terms of
--   the other. the RefSerialize monad has been introduced to permit
--   IResource objects to be serialized as part of larger structures that
--   embody them. This is necessary for the Workdlow package.
--   
--   The keyResource string must be a unique since this is used to index it
--   in the hash table. when accessing a resource, the user must provide a
--   partial object for wich the key can be obtained. for example:
--   
--   <pre>
--   data Person= Person{name, surname:: String, account :: Int ....)
--   
--   keyResource Person n s ...= n++s
--   </pre>
--   
--   the data being accesed must have the fields used by keyResource
--   filled. For example
--   
--   <pre>
--   readResource Person {name=<a>John</a>, surname= <a>Adams</a>}
--   </pre>
--   
--   leaving the rest of the fields undefined
--   
--   IResource has defaults definitions for all the methods except
--   keyResource Either one or other serializer must be defiened for
--   default witeResource, readResource and delResource
class IResource a
keyResource :: (IResource a) => a -> String
serialize :: (IResource a) => a -> String
deserialize :: (IResource a) => String -> a
tshowp :: (IResource a) => a -> ST String
treadp :: (IResource a) => ST a
defPath :: (IResource a) => a -> String
readResource :: (IResource a) => a -> IO (Maybe a)
writeResource :: (IResource a) => a -> IO ()
delResource :: (IResource a) => a -> IO ()

-- | Resources returned by <tt>withSTMResources'</tt>
data Resources a b

-- | forces a retry
Retry :: Resources a b
Resources :: [a] -> [a] -> b -> Resources a b

-- | resources to be inserted back in the cache
toAdd :: Resources a b -> [a]

-- | resources to be deleted from the cache and from permanent storage
toDelete :: Resources a b -> [a]

-- | result to be returned
toReturn :: Resources a b -> b

-- | <pre>
--   resources= Resources  [] [] ()
--   </pre>
resources :: Resources a ()

-- | getTMVars return the TMVar that wraps the resources for which the keys
--   are given . | it return Nothing if a TMVar with this object has not
--   been allocated These TMVars can be used in explicit user constructed
--   atomic blocks Additionally, the TMVars remain in the cache and can be
--   accessed and updated by the rest of the TCache methods. the content of
--   the TMVars are written every time the cache is syncronized with the
--   storage until releaseTMVars is called
getTMVars :: (IResource a) => [a] -> STM [Maybe (TMVar a)]

-- | getTMVarsIO does not search for a TMVar in the cache like getTMVars.
--   Instead of this getTMVarsIO creates a list of TMVars with the content
--   given in the list of resourcees and add these TMVars to the cache and
--   return them. the content of the TMVars are written every time the
--   cache is syncronized with the storage until releaseTMVars is called
getTMVarsIO :: (IResource a) => [a] -> IO [TMVar a]

-- | this is the main function for the *Resources primitivas, all the rest
--   derive from it. the Res structure processed by the with*Resources
--   primitives are more efficient for cached TMVars because the internal
--   loop is never retried, since all the necessary resources at the
--   beginning so no costly retries are necessary. The advantage increases
--   with the complexity of the process function passed to withSTMResources
--   is interpreted as such: -toUpdate secton is used to update the
--   retrieved resources in the same order. if the resource dont exist, it
--   is created. Nothing means do nothing as usual. extra resources are not
--   considered, it uses the rules of zip. -toAdd: additional resources not
--   read in the first parameter of withSTMResources are created/updated
--   with toAdd -toDelete: obvious -toReturn: will be returned by the call
withSTMResources :: (IResource a) => [a] -> ([Maybe a] -> Resources a x) -> STM x

-- | to atomically add/modify many objects in the cache :: (IResource
--   a)=&gt; [a] list of resources to be retrieve -&gt; ([Maybe a]-&gt;
--   [a]) function that process the retrieved resources -&gt; IO () and
--   return a list of objects to be inserted/modified
withResources :: (IResource a) => [a] -> ([Maybe a] -> [a]) -> IO ()

-- | update of a single object in the cache :: (IResource a)=&gt; a same as
--   withResources , but for one only object -&gt; ([Maybe a]-&gt; a) -&gt;
--   IO ()
withResource :: (IResource a) => a -> (Maybe a -> a) -> IO ()

-- | to read a resource from the cache
getResources :: (IResource a) => [a] -> IO [Maybe a]
getResource :: (IResource a) => a -> IO (Maybe a)
deleteResources :: (IResource a) => [a] -> IO ()
deleteResource :: (IResource a) => a -> IO ()
type Cache a = IORef (Ht a, Integer)

-- | set the cache. this is useful for hot loaded modules that will update
--   an existing cache
setCache :: (Ht a, Integer) -> IO ()

-- | newCache creates a new cache
newCache :: IO (Ht a, Integer)
refcache :: Cache a
syncCache :: (IResource a) => IORef (HashTable String (Block a), Integer) -> IO ()

-- | start the thread that clean and writes on the persistent storage.
--   Otherwise, clearSyncCache must be invoked explicitly or no persistence
--   will exist :: (IResource a) =&gt;Cache a --The cache reference -&gt;
--   Int --number of seconds betwen checks -&gt; (Integer-&gt; Integer-&gt;
--   Bool) --The user-defined check-for-cleanup-from-cache for each object
--   (when this function return True, the object is removed from cache)
--   -&gt; Int --The max number of objects in the cache, if more, the
--   cleanup start -&gt; &gt;IO ThreadId --Identifier of the thread created
clearSyncCacheProc :: (IResource a) => Cache a -> Int -> (Integer -> Integer -> Integer -> Bool) -> Int -> IO ThreadId

-- | To drop from the cache all the elems not accesed since half the time
--   between now and the last sync the default check procedure :: Integer
--   -- current time in seconds -&gt; Integer --last access time for a
--   given object -&gt; Integer --last cache syncronization (with the
--   persisten storage) -&gt; Bool --return true for all the elems not
--   accesed since half the time between now and the last sync
defaultCheck :: Integer -> Integer -> Integer -> Bool
readFileStrict :: FilePath -> IO [Char]


-- | Data.TCache.TMVar.Dynamic: A dynamic interface for TCache using TMVars
--   
--   Dynamic present essentially the same methods than Data.TCache. The
--   added functionality is the management of IDynamic types. Any datatype
--   that is instance of IResource and Typeable can be handled mixed with
--   any other datatype. TCache.Dynamic is essentially a TCache working
--   with a single datatype: IDynamic that is indexable and serializable.
--   You dont need to do anything special except to define the IResource
--   and typeable instances for your particular datatype. Also, before use,
--   your datatype must be registered (with registerType, see example in
--   the package).
--   
--   there are basically two types of methods:
--   
--   <ul>
--   <li>*Resource(s) : manage one type of data, Are the same than
--   Data.TCache. The marsalling to and from IDynamic is managed
--   internally</li>
--   <li>*DResource(s): handle the IDynamic type. you must wrap your
--   datatype (with toIDyn) and unwap it (with fromIDyn)</li>
--   </ul>
--   
--   The first set allows different modules to handle their particular kind
--   of data without regard that it is being handled in the same cache with
--   other datatypes.
--   
--   The second set allows to handle, transact etc with many datatypes at
--   the same time.
--   
--   There is also a useful Key object whose purpose is to retrieve any
--   objecto fo any datatype by its sting key
--   
--   Also the parameter refcache has been dropped from the methods that
--   used it (the syncronization methods)
module Data.TCache.TMVar.Dynamic

-- | Interface that must be defined for every object being cached.
--   <a>readResource</a> and <a>writeResource</a> are implemented by
--   default as read-write to files with its key as filename
--   <a>serialize</a> and <a>deserialize</a> are specified just to allow
--   these defaults. If you define your own persistence, then
--   <tt>serialize</tt> and <tt>deserialize</tt> are not needed. The
--   package <tt>Workflow</tt> need them anyway.
--   
--   minimal definition: keyResource, serialize, deserialize
--   
--   While serialize and deserialize are agnostic about the way of
--   converison to strings, either binary or textual, treadp and tshowp use
--   the monad defined in the RefSerialize package. Both ways of
--   serialization are alternative. one is defined by default in terms of
--   the other. the RefSerialize monad has been introduced to permit
--   IResource objects to be serialized as part of larger structures that
--   embody them. This is necessary for the Workdlow package.
--   
--   The keyResource string must be a unique since this is used to index it
--   in the hash table. when accessing a resource, the user must provide a
--   partial object for wich the key can be obtained. for example:
--   
--   <pre>
--   data Person= Person{name, surname:: String, account :: Int ....)
--   
--   keyResource Person n s ...= n++s
--   </pre>
--   
--   the data being accesed must have the fields used by keyResource
--   filled. For example
--   
--   <pre>
--   readResource Person {name=<a>John</a>, surname= <a>Adams</a>}
--   </pre>
--   
--   leaving the rest of the fields undefined
--   
--   IResource has defaults definitions for all the methods except
--   keyResource Either one or other serializer must be defiened for
--   default witeResource, readResource and delResource
class IResource a
keyResource :: (IResource a) => a -> String
serialize :: (IResource a) => a -> String
deserialize :: (IResource a) => String -> a
tshowp :: (IResource a) => a -> ST String
treadp :: (IResource a) => ST a
defPath :: (IResource a) => a -> String
readResource :: (IResource a) => a -> IO (Maybe a)
writeResource :: (IResource a) => a -> IO ()
delResource :: (IResource a) => a -> IO ()

-- | Resources returned by <tt>withSTMResources'</tt>
data Resources a b

-- | forces a retry
Retry :: Resources a b
Resources :: [a] -> [a] -> b -> Resources a b

-- | resources to be inserted back in the cache
toAdd :: Resources a b -> [a]

-- | resources to be deleted from the cache and from permanent storage
toDelete :: Resources a b -> [a]

-- | result to be returned
toReturn :: Resources a b -> b

-- | <pre>
--   resources= Resources  [] [] ()
--   </pre>
resources :: Resources a ()

-- | set the cache. this is useful for hot loaded modules that will update
--   an existing cache
setCache :: (Ht a, Integer) -> IO ()
refcache :: Cache a

-- | To drop from the cache all the elems not accesed since half the time
--   between now and the last sync the default check procedure :: Integer
--   -- current time in seconds -&gt; Integer --last access time for a
--   given object -&gt; Integer --last cache syncronization (with the
--   persisten storage) -&gt; Bool --return true for all the elems not
--   accesed since half the time between now and the last sync
defaultCheck :: Integer -> Integer -> Integer -> Bool
readFileStrict :: FilePath -> IO [Char]
data IDynamic
IDynamic :: a -> IDynamic
type Cache a = IORef (Ht a, Integer)

-- | DynamicInterface groups a set of default method calls to handle
--   dynamic objects. It is not necessary to derive instances from it
class DynamicInterface x
toIDyn :: (DynamicInterface x) => x -> IDynamic
registerType :: (DynamicInterface x) => IO x
fromIDyn :: (DynamicInterface x) => IDynamic -> x
unsafeFromIDyn :: (DynamicInterface x) => IDynamic -> x

-- | Key datatype can be used to read any object trough the Dynamic
--   interface.
--   
--   <pre>
--   data Key =  Key <a>TypeRep</a> String deriving Typeable
--   </pre>
--   
--   Example
--   
--   <pre>
--   mst &lt;- <tt>getDResource</tt> $ <a>Key</a> type <tt>keyofDesiredObject</tt>
--              case mst of
--                Nothing -&gt; error $ "not found "++ key
--                Just (idyn) -&gt;  fromIDyn idyn :: DesiredDatatype}
--   </pre>
data Key
Key :: TypeRep -> String -> Key
getTMVars :: [IDynamic] -> STM [Maybe (TMVar IDynamic)]
getTMVarsIO :: [IDynamic] -> IO [TMVar IDynamic]
withDResource :: IDynamic -> (Maybe IDynamic -> IDynamic) -> IO ()
withDResources :: [IDynamic] -> ([Maybe IDynamic] -> [IDynamic]) -> IO ()
withDSTMResources :: [IDynamic] -> ([Maybe IDynamic] -> Resources IDynamic x) -> STM x
getDResource :: IDynamic -> IO (Maybe IDynamic)
getDResources :: [IDynamic] -> IO [Maybe IDynamic]

-- | return error if any resource is not found
deleteDResource :: IDynamic -> IO ()
deleteDResources :: [IDynamic] -> IO ()
syncCache :: IO ()
clearSyncCacheProc :: Int -> (Integer -> Integer -> Integer -> Bool) -> Int -> IO ThreadId
withResource :: (Typeable a, Typeable b, IResource a, IResource b) => a -> (Maybe a -> b) -> IO ()
withResources :: (Typeable a, Typeable b, IResource a, IResource b) => [a] -> ([Maybe a] -> [b]) -> IO ()
withSTMResources :: (Typeable a, Typeable b, IResource a, IResource b) => [a] -> ([Maybe a] -> Resources b x) -> STM x
getResource :: (Typeable a, Typeable b, IResource a, IResource b) => a -> IO (Maybe b)
getResources :: (Typeable a, Typeable b, IResource a, IResource b) => [a] -> IO [Maybe b]
deleteResource :: (Typeable a, IResource a) => a -> IO ()
deleteResources :: (Typeable a, IResource a) => [a] -> IO ()

module Data.TCache

-- | Interface that must be defined for every object being cached.
--   <a>readResource</a> and <a>writeResource</a> are implemented by
--   default as read-write to files with its key as filename
--   <a>serialize</a> and <a>deserialize</a> are specified just to allow
--   these defaults. If you define your own persistence, then
--   <tt>serialize</tt> and <tt>deserialize</tt> are not needed. The
--   package <tt>Workflow</tt> need them anyway.
--   
--   minimal definition: keyResource, serialize, deserialize
--   
--   While serialize and deserialize are agnostic about the way of
--   converison to strings, either binary or textual, treadp and tshowp use
--   the monad defined in the RefSerialize package. Both ways of
--   serialization are alternative. one is defined by default in terms of
--   the other. the RefSerialize monad has been introduced to permit
--   IResource objects to be serialized as part of larger structures that
--   embody them. This is necessary for the Workdlow package.
--   
--   The keyResource string must be a unique since this is used to index it
--   in the hash table. when accessing a resource, the user must provide a
--   partial object for wich the key can be obtained. for example:
--   
--   <pre>
--   data Person= Person{name, surname:: String, account :: Int ....)
--   
--   keyResource Person n s ...= n++s
--   </pre>
--   
--   the data being accesed must have the fields used by keyResource
--   filled. For example
--   
--   <pre>
--   readResource Person {name=<a>John</a>, surname= <a>Adams</a>}
--   </pre>
--   
--   leaving the rest of the fields undefined
--   
--   IResource has defaults definitions for all the methods except
--   keyResource Either one or other serializer must be defiened for
--   default witeResource, readResource and delResource
class IResource a
keyResource :: (IResource a) => a -> String
serialize :: (IResource a) => a -> String
deserialize :: (IResource a) => String -> a
tshowp :: (IResource a) => a -> ST String
treadp :: (IResource a) => ST a
defPath :: (IResource a) => a -> String
readResource :: (IResource a) => a -> IO (Maybe a)
writeResource :: (IResource a) => a -> IO ()
delResource :: (IResource a) => a -> IO ()

-- | Resources returned by <tt>withSTMResources'</tt>
data Resources a b

-- | forces a retry
Retry :: Resources a b
Resources :: [a] -> [a] -> b -> Resources a b

-- | resources to be inserted back in the cache
toAdd :: Resources a b -> [a]

-- | resources to be deleted from the cache and from permanent storage
toDelete :: Resources a b -> [a]

-- | result to be returned
toReturn :: Resources a b -> b

-- | <pre>
--   resources= Resources  [] [] ()
--   </pre>
resources :: Resources a ()

-- | getTVars return the TVar that wraps the resources for which the keys
--   are given . | it return <tt>Nothing</tt> if a TVar with this object
--   has not been allocated These TVars can be used as usual in explicit
--   user constructed atomic blocks Additionally, the retrieved TVars
--   remain in the cache and can be accessed and updated by the rest of the
--   TCache methods. to keep the consistence in the serialized data, the
--   content of the TVars are written every time the cache is syncronized
--   with the storage until releaseTVars is called
getTVars :: (IResource a) => [a] -> STM [Maybe (TVar a)]

-- | releaseTVars permits the TVars captured by getTVars to be released. so
--   they can be discarded when not used. Do this when you no longer need
--   to use them directly in atomic blocks.
releaseTVars :: (IResource a) => [a] -> STM ()

-- | getTVarsIO does not search for a TVar in the cache like getTVars.
--   Instead of this getTVarsIO creates a list of TVars with the content
--   given in the list of resourcees and add these TVars to the cache and
--   return them. the content of the TVars are written every time the cache
--   is syncronized with the storage until releaseTVars is called
getTVarsIO :: (IResource a) => [a] -> IO [TVar a]

-- | this is the main function for the *Resource calls. All the rest derive
--   from it. The results are kept in the STM monad so it can be part of a
--   larger STM transaction involving other TVars The <a>Resources</a>
--   register returned by the user-defined function is interpreted as such:
--   
--   <a>toAdd</a>: additional resources not read in the first parameter of
--   withSTMResources are created/updated with toAdd
--   
--   <a>toDelete</a>: from the cache and from permanent storage
--   
--   <a>toReturn</a>: will be returned by withSTMResources
withSTMResources :: (IResource a) => [a] -> ([Maybe a] -> Resources a x) -> STM x

-- | to atomically add/modify many objects in the cache
--   
--   <pre>
--   withResources rs f=  atomically $ withSTMResources rs f1 &gt;&gt; return() where   f1 mrs= let as= f mrs in  Resources  as [] ()
--   </pre>
withResources :: (IResource a) => [a] -> ([Maybe a] -> [a]) -> IO ()

-- | update of a single object in the cache
--   
--   <pre>
--   withResource r f= withResources [r] ([mr]-&gt; [f mr])
--   </pre>
withResource :: (IResource a) => a -> (Maybe a -> a) -> IO ()
getResources :: (IResource a) => [a] -> IO [Maybe a]

-- | to read a resource from the cache.
--   
--   <pre>
--   getResource r= do{mr&lt;- getResources [r];return $! head mr}
--   </pre>
getResource :: (IResource a) => a -> IO (Maybe a)

-- | delete the list of resources from cache and from persistent storage.
--   
--   <pre>
--   deleteResources rs= atomically $ withSTMResources rs f1 where  f1 mrs = Resources  [] (catMaybes mrs) ()
--   </pre>
deleteResources :: (IResource a) => [a] -> IO ()

-- | delete the resource from cache and from persistent storage.
--   
--   <pre>
--   deleteResource r= deleteResources [r]
--   </pre>
deleteResource :: (IResource a) => a -> IO ()
type Cache a = IORef (Ht a, Integer)

-- | set the cache. this is useful for hot loaded modules that will update
--   an existing cache. Experimental
setCache :: (Ht a, Integer) -> IO ()

-- | newCache creates a new cache. Experimental
newCache :: IO (Ht a, Integer)
refcache :: Cache a

-- | Force the atomic write of all the cached objects into permanent
--   storage useful for termination
syncCache :: (IResource a) => Cache a -> IO ()

-- | Cache handling
--   
--   Start the thread that clean and writes on the persistent storage.
--   Otherwise, clearSyncCache must be invoked explicitly or no persistence
--   will exist :: (IResource a) =&gt;Cache a -&gt; Int --number of seconds
--   betwen checks -&gt; (Integer-&gt; Integer-&gt; Bool) --The
--   user-defined check-for-cleanup-from-cache for each object (when this
--   function return True, the object is removed from cache) -&gt; Int
--   --The max number of objects in the cache, if more, the cleanup start
--   -&gt; &gt;IO ThreadId --Identifier of the thread created
clearSyncCacheProc :: (IResource a) => Cache a -> Int -> (Integer -> Integer -> Integer -> Bool) -> Int -> IO ThreadId

-- | To drop from the cache all the elems not accesed since half the time
--   between now and the last sync ths is a default cache clearance
--   procedure -- it is invoke when the cache size exceeds the defined in
--   <a>clearSyncCacheProc</a>
defaultCheck :: Integer -> Integer -> Integer -> Bool
readFileStrict :: FilePath -> IO [Char]


-- | Data.TCache.Dynamic: A dynamic interface for TCache so that mixed
--   datatypes can be managed participating in a single transaction. The
--   objects are encapsulated in a <a>IDynamic</a> datatype, that is d
--   Dynamic type that is serializable and indexable
--   
--   Dynamic present essentially the same methods than Data.TCache. The
--   added functionality is the management of IDynamic types. Any datatype
--   that is instance of IResource and Typeable can be handled mixed with
--   any other datatype. TCache.Dynamic is essentially a TCache working
--   with a single datatype: IDynamic that is indexable and serializable.
--   You dont need to do anything special except to define Typeable
--   besides the IResource instance for your particular datatype. Also,
--   before use, your datatype must be registered (with
--   <a>registerType</a>, see example in the package).
--   
--   there are basically two types of methods in this module:
--   
--   <ul>
--   <li><tt>with(STM)Resource(s)</tt> calls: manage one single type of
--   data, in the same way than the naked <tt>Data.TCache</tt> module, Are
--   the same than Data.TCache. The marsalling to and from IDynamic is
--   managed internally. These calls do exactly the same than the TCache
--   calls with the same name these cals allows different modules to handle
--   their particular kind of data without regard that it is being handled
--   in the same cache with other datatypes.</li>
--   <li><tt>wthD(STM)Resource(s)</tt>: are new, and handle the IDynamic
--   type. The user must wrap your datatypes (with toIDyn) and unwap it
--   (with fromIDyn) These call permts to handle arbitrary types at the
--   same time and partticipate in transactions.</li>
--   </ul>
--   
--   There is also a useful <a>Key</a> object whose purpose is to retrieve
--   any objecto fo any datatype by its sting key
--   
--   Also the parameter <tt>refcache</tt> has been dropped from the methods
--   that used it (the syncronization methods)
module Data.TCache.Dynamic

-- | Interface that must be defined for every object being cached.
--   <a>readResource</a> and <a>writeResource</a> are implemented by
--   default as read-write to files with its key as filename
--   <a>serialize</a> and <a>deserialize</a> are specified just to allow
--   these defaults. If you define your own persistence, then
--   <tt>serialize</tt> and <tt>deserialize</tt> are not needed. The
--   package <tt>Workflow</tt> need them anyway.
--   
--   minimal definition: keyResource, serialize, deserialize
--   
--   While serialize and deserialize are agnostic about the way of
--   converison to strings, either binary or textual, treadp and tshowp use
--   the monad defined in the RefSerialize package. Both ways of
--   serialization are alternative. one is defined by default in terms of
--   the other. the RefSerialize monad has been introduced to permit
--   IResource objects to be serialized as part of larger structures that
--   embody them. This is necessary for the Workdlow package.
--   
--   The keyResource string must be a unique since this is used to index it
--   in the hash table. when accessing a resource, the user must provide a
--   partial object for wich the key can be obtained. for example:
--   
--   <pre>
--   data Person= Person{name, surname:: String, account :: Int ....)
--   
--   keyResource Person n s ...= n++s
--   </pre>
--   
--   the data being accesed must have the fields used by keyResource
--   filled. For example
--   
--   <pre>
--   readResource Person {name=<a>John</a>, surname= <a>Adams</a>}
--   </pre>
--   
--   leaving the rest of the fields undefined
--   
--   IResource has defaults definitions for all the methods except
--   keyResource Either one or other serializer must be defiened for
--   default witeResource, readResource and delResource
class IResource a
keyResource :: (IResource a) => a -> String
serialize :: (IResource a) => a -> String
deserialize :: (IResource a) => String -> a
tshowp :: (IResource a) => a -> ST String
treadp :: (IResource a) => ST a
defPath :: (IResource a) => a -> String
readResource :: (IResource a) => a -> IO (Maybe a)
writeResource :: (IResource a) => a -> IO ()
delResource :: (IResource a) => a -> IO ()

-- | Resources returned by <tt>withSTMResources'</tt>
data Resources a b

-- | forces a retry
Retry :: Resources a b
Resources :: [a] -> [a] -> b -> Resources a b

-- | resources to be inserted back in the cache
toAdd :: Resources a b -> [a]

-- | resources to be deleted from the cache and from permanent storage
toDelete :: Resources a b -> [a]

-- | result to be returned
toReturn :: Resources a b -> b

-- | <pre>
--   resources= Resources  [] [] ()
--   </pre>
resources :: Resources a ()

-- | set the cache. this is useful for hot loaded modules that will update
--   an existing cache. Experimental
setCache :: (Ht a, Integer) -> IO ()
refcache :: Cache a

-- | To drop from the cache all the elems not accesed since half the time
--   between now and the last sync ths is a default cache clearance
--   procedure -- it is invoke when the cache size exceeds the defined in
--   <a>clearSyncCacheProc</a>
defaultCheck :: Integer -> Integer -> Integer -> Bool
readFileStrict :: FilePath -> IO [Char]
data IDynamic
IDynamic :: a -> IDynamic
type Cache a = IORef (Ht a, Integer)

-- | DynamicInterface groups a set of default method calls to handle
--   dynamic objects. It is not necessary to derive instances from it
class DynamicInterface x
toIDyn :: (DynamicInterface x) => x -> IDynamic
registerType :: (DynamicInterface x) => IO x
fromIDyn :: (DynamicInterface x) => IDynamic -> x
unsafeFromIDyn :: (DynamicInterface x) => IDynamic -> x
safeFromIDyn :: (DynamicInterface x) => IDynamic -> Maybe x

-- | Key datatype can be used to read any object trough the Dynamic
--   interface.
--   
--   <pre>
--   data Key =  Key <a>TypeRep</a> String deriving Typeable
--   </pre>
--   
--   Example
--   
--   <pre>
--   mst &lt;- <tt>getDResource</tt> $ <a>Key</a> type <tt>keyofDesiredObject</tt>
--              case mst of
--                Nothing -&gt; error $ "not found "++ key
--                Just (idyn) -&gt;  fromIDyn idyn :: DesiredDatatype}
--   </pre>
data Key
Key :: TypeRep -> String -> Key

-- | getTVars return the TVar that wraps the resources for which the keys
--   are given . | it return <tt>Nothing</tt> if a TVar with this object
--   has not been allocated These TVars can be used as usual in explicit
--   user constructed atomic blocks Additionally, the retrieved TVars
--   remain in the cache and can be accessed and updated by the rest of the
--   TCache methods. to keep the consistence in the serialized data, the
--   content of the TVars are written every time the cache is syncronized
--   with the storage until releaseTVars is called See
--   <tt>Data.TCache.getTVars</tt>
getTVars :: [IDynamic] -> STM [Maybe (TVar IDynamic)]
releaseTVars :: [IDynamic] -> STM ()
getTVarsIO :: [IDynamic] -> IO [TVar IDynamic]

-- | handles Dynamic objects using <tt>Data.TCache.withResource</tt>
--   
--   <pre>
--   withDResource =  Data.TCache..withResource
--   </pre>
withDResource :: IDynamic -> (Maybe IDynamic -> IDynamic) -> IO ()
withDResources :: [IDynamic] -> ([Maybe IDynamic] -> [IDynamic]) -> IO ()

-- | this is the main function for the *Resource calls. All the rest derive
--   from it. The results are kept in the STM monad so it can be part of a
--   larger STM transaction involving other TVars The <tt>Resources</tt>
--   register returned by the user-defined function is interpreted as such:
--   
--   <tt>toAdd</tt>: additional resources not read in the first parameter
--   of withSTMResources are created/updated with toAdd
--   
--   <tt>toDelete</tt>: from the cache and from permanent storage
--   
--   <tt>toReturn</tt>: will be returned by withSTMResources
withDSTMResources :: [IDynamic] -> ([Maybe IDynamic] -> Resources IDynamic x) -> STM x

-- | <pre>
--   getDResource  = Data.TCache.getResource
--   </pre>
getDResource :: IDynamic -> IO (Maybe IDynamic)

-- | <pre>
--   getDResources  = Data.TCache.getResources
--   </pre>
getDResources :: [IDynamic] -> IO [Maybe IDynamic]

-- | retrieve a list of objects and return error if any resource is not
--   found. instead of Nothing
--   
--   delete a resource from the cache and the storage
deleteDResource :: IDynamic -> IO ()

-- | delete a list of resources from the cache and the storage
deleteDResources :: [IDynamic] -> IO ()
syncCache :: IO ()

-- | Start the thread that clean and writes on the persistent storage.
--   Otherwise, syncCache must be invoked explicitly or no persistence will
--   exist
clearSyncCacheProc :: Int -> (Integer -> Integer -> Integer -> Bool) -> Int -> IO ThreadId

-- | methods that handle a single datatype.
--   
--   similar to <tt>Data.TCache.withResource</tt>. The fact that this
--   method may return a type different that the source type permits to use
--   ' Key' objects
withResource :: (Typeable a, Typeable b, IResource a, IResource b) => a -> (Maybe a -> b) -> IO ()

-- | similar to <tt>Data.TCache.withResources</tt>. The fact that this
--   method may return a type different that the source type permits to use
--   ' Key' objects
withResources :: (Typeable a, Typeable b, IResource a, IResource b) => [a] -> ([Maybe a] -> [b]) -> IO ()

-- | similar to <tt>Data.TCache.withSTMResources</tt>. The return in the
--   STM monad permits to participate in larger STM transactions The fact
--   that this method may return a type different that the source type
--   permits to use ' Key' objects
withSTMResources :: (Typeable a, Typeable b, IResource a, IResource b) => [a] -> ([Maybe a] -> Resources b x) -> STM x

-- | similar to Data.<tt>TCache.getResource</tt>. The fact that this method
--   may return a type different that the source type permits to use ' Key'
--   objects
getResource :: (Typeable a, Typeable b, IResource a, IResource b) => a -> IO (Maybe b)

-- | similar to <tt>Data.TCache.getResources</tt>. The fact that this
--   method may return a type different that the source type permits to use
--   ' Key' objects
getResources :: (Typeable a, Typeable b, IResource a, IResource b) => [a] -> IO [Maybe b]

-- | similar to <tt>Data.TCache.deleteResource</tt>
deleteResource :: (Typeable a, IResource a) => a -> IO ()

-- | similar to <tt>Data.TCache.deleteResource</tt>
deleteResources :: (Typeable a, IResource a) => [a] -> IO ()