-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | A Transactional cache with user-defined persistence
--
-- TCache is a transactional cache with configurable persitence. It
-- allows conventional STM transactions for objects that syncronize with
-- their user defined storages. Default persistence in files is provided
-- for testing purposes State in memory and into permanent storage is
-- transactionally coherent. 0.9.0.1 : Solves a bug when object keys
-- generate invalid filenames. changes in defaultPersistence to further
-- separate serialization from input-output
--
--
-- - 9: This version now has full text search. Serialization is now
-- trough byteStrings
--
--
-- This version support the backward compatible stuff, that permits
-- transparent retrievals of objects and transcactions between objects
-- without directly using STM references ('with*Resource(s)' calls), Now
-- it goes in the oposite direction by providing explicit STM persistent
-- references (called 'DBRefś') that leverage the nice and traditional
-- haskell reference syntax for performing database transactions.
--
-- DBRefs are in essence, persistent TVars indexed in the cache,
-- with a traditional readDBRef, writeDBRef Haskell
-- interface in the STM monad. Additionally, because DBRefs are
-- serializable, they can be embeded in serializable registers. Because
-- they are references,they point to other serializable registers. This
-- permits persistent mutable and efficient Inter-object relations.
--
-- Triggers are also included in this release. They are user defined
-- hooks that are called back on register updates. That can be used for
-- easing the actualization of inter-object relations and also permit
-- more higuer level and customizable accesses. The internal indexes used
-- for the query language uses triggers.
--
-- It also implements an straighforwards non-intrusive pure-haskell type
-- safe query language based on register field relations. This module
-- must be imported separately. See Data.TCache.IndexQuery for
-- further information
--
-- Now the file persistence is more reliable.The IO reads are safe inside
-- STM transactions.
--
-- To ease the implementation of other user-defined persistence,
-- Data.TCache.DefaultPersistence needed to be imported explcitly
-- for deriving file persistence instances.
--
-- The 0.9 version adds full text indexation and search, incorporated in
-- the experimental query language
--
-- It also changes the default Persistence mechanism. Now ByteStrings are
-- used for serialization and deserialization . a Serializable class and
-- a Persist structure decouple serialization to/from bytestring and
-- write-read to file. Both can be redefined separately, so default
-- persistence can be changed with setPersist to write to blobs in
-- databases, for example. Default persistence has'nt to be in files.
@package TCache
@version 0.9.0.2
module Data.TCache.IResource
-- | An IResource instance that must be defined for every object being
-- cached. there are a set of implicit IResource instance trough utiliy
-- classes (See below)
class IResource a
keyResource :: IResource a => a -> String
readResourceByKey :: IResource a => String -> IO (Maybe a)
writeResource :: IResource a => a -> IO ()
delResource :: IResource a => a -> IO ()
-- | Resources data definition used by withSTMResources
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
-- | Empty resources: resources= Resources [] [] ()
resources :: Resources a ()
module Data.TCache.Defs
type AccessTime = Integer
type ModifTime = Integer
data Status a
NotRead :: Status a
DoNotExist :: Status a
Exist :: a -> Status a
data Elem a
Elem :: a -> AccessTime -> ModifTime -> Elem a
type TPVar a = TVar (Status (Elem a))
data DBRef a
DBRef :: String -> (TPVar a) -> DBRef a
castErr :: (Typeable a1, Typeable a) => a -> a1
instance Typeable1 Status
instance Typeable1 Elem
instance Typeable1 DBRef
module Data.TCache.Triggers
data DBRef a
DBRef :: String -> (TPVar a) -> DBRef a
data Elem a
Elem :: a -> AccessTime -> ModifTime -> Elem a
data Status a
NotRead :: Status a
DoNotExist :: Status a
Exist :: a -> Status a
-- | Add an user defined trigger to the list of triggers Trriggers are
-- called just before an object of the given type is created, modified or
-- deleted. The DBRef to the object and the new value is passed to the
-- trigger. The called trigger function has two parameters: the DBRef
-- being accesed (which still contains the old value), and the new value.
-- If the content of the DBRef is being deleted, the second parameter is
-- Nothing. if the DBRef contains Nothing, then the object is
-- being created
addTrigger :: (IResource a, Typeable a) => ((DBRef a) -> Maybe a -> STM ()) -> IO ()
applyTriggers :: (IResource a, Typeable a) => [DBRef a] -> [Maybe a] -> STM ()
instance Typeable1 TriggerType
-- | This module provides default persistence , understood as retrievong
-- and storing the object in serialized blobs but also to compose a SQL
-- string and write it to a databases. for Indexable and serializable
-- instances. The user can define it with setPersist. If the user does
-- not set it, persistence in files is used.
module Data.TCache.DefaultPersistence
-- | Indexable is an utility class used to derive instances of IResource
--
-- Example:
--
--
-- data Person= Person{ pname :: String, cars :: [DBRef Car]} deriving (Show, Read, Typeable)
-- data Car= Car{owner :: DBRef Person , cname:: String} deriving (Show, Read, Eq, Typeable)
--
--
-- Since Person and Car are instances of Read ans Show, by
-- defining the Indexable instance will implicitly define the
-- IResource instance for file persistence:
--
--
-- instance Indexable Person where key Person{pname=n} = "Person " ++ n
-- instance Indexable Car where key Car{cname= n} = "Car " ++ n
--
class Indexable a where defPath = const "TCacheData/"
key :: Indexable a => a -> String
defPath :: Indexable a => a -> String
-- | Serialize is an abstract serialization ionterface in order to define
-- implicit instances of IResource. The deserialization must be as lazy
-- as possible if deserialized objects contain DBRefs, lazy
-- deserialization avoid unnecesary DBRef instantiations when they are
-- not accessed, since DBRefs instantiations involve extra cache lookups
-- For this reason serializationdeserialization is tofrom ordinary
-- Strings serialization/deserialization are not performance critical in
-- TCache
--
-- Read, Show, instances are implicit instances of Serializable
--
--
-- serialize = show
-- deserialize= read
--
--
-- Since write and read to disk of to/from the cache must not be very
-- often The performance of serialization is not critical.
class Serializable a | a -> where setPersist _ = defaultPersist
serialize :: Serializable a => a -> ByteString
deserialize :: Serializable a => ByteString -> a
setPersist :: Serializable a => a -> Persist
data Persist
-- | delete
Persist :: (String -> IO (Maybe ByteString)) -> (String -> ByteString -> IO ()) -> (String -> IO ()) -> Persist
-- | read
readByKey :: Persist -> (String -> IO (Maybe ByteString))
-- | write
write :: Persist -> (String -> ByteString -> IO ())
delete :: Persist -> (String -> IO ())
instance (Typeable a, Indexable a, Serializable a) => IResource a
-- | TCache is a transactional cache with configurable persitence that
-- permits STM transactions with objects thar syncronize sincromous or
-- asyncronously with their user defined storages. Default persistence in
-- files is provided for testing purposes
--
-- In this release some stuff has been supressed without losing
-- functionality. Dynamic interfaces are not needed since TCache can
-- handle heterogeneous data. The new things in this release, besides the
-- backward compatible stuf are:
--
-- TCache now implements. ''DBRef' 's . They are persistent STM
-- references with a traditional readDBRef, writeDBRef
-- Haskell interface. simitar to TVars, but with aded. persistence
-- Additionally, because DBRefs are serializable, they can be embeded in
-- serializable registers. Because they are references,they point to
-- other serializable registers. This permits persistent mutable
-- Inter-object relations
--
-- Triggers are user defined hooks that are called back on register
-- updates. That can be used for:
--
--
-- - ease the work of maintain actualized the inter-object
-- relations
-- - permit more higuer level and customizable accesses
--
--
-- Data.TCache.IndexQuery implements an straighforwards pure
-- haskell type safe query language based on register field relations.
-- This module must be imported separately. see
-- Data.TCache.IndexQuery for further information
--
-- The file persistence is now more reliable, and the embedded IO reads
-- inside STM transactions are safe.
--
-- To ease the implementation of other user-defined persistence,
-- Data.TCache.FIlePersistence must be imported for deriving file
-- persistence instances
module Data.TCache
-- | Perform a series of STM actions atomically.
--
-- You cannot use atomically inside an unsafePerformIO or
-- unsafeInterleaveIO. Any attempt to do so will result in a
-- runtime error. (Reason: allowing this would effectively allow a
-- transaction inside a transaction, depending on exactly when the thunk
-- is evaluated.)
--
-- However, see newTVarIO, which can be called inside
-- unsafePerformIO, and which allows top-level TVars to be
-- allocated.
atomically :: STM a -> IO a
-- | A monad supporting atomic memory transactions.
data STM a :: * -> *
data DBRef a
-- | get the reference to the object in the cache. if it does not exist,
-- the reference is created empty. Every execution of getDBRef
-- returns the same unique reference to this key, so it can be safely
-- considered pure. This is a property useful because deserialization of
-- objects with unused embedded DBRef's do not need to marshall them
-- eagerly Tbis also avoid unnecesary cache lookups of the pointed
-- objects.
getDBRef :: (Typeable a, IResource a) => String -> DBRef a
-- | return the key of the object pointed to by the DBRef
keyObjDBRef :: DBRef a -> String
-- | Create the object passed as parameter (if it does not exist) and --
-- return its reference in the IO monad. -- If an object with the same
-- key already exists, it is returned as is -- If not, the reference is
-- created with the new value. -- If you like to update in any case, use
-- getDBRef and writeDBRef combined newDBRefIO ::
-- (IResource a,Typeable a) => a -> IO (DBRef a) newDBRefIO x= do
-- let key = keyResource x mdbref <- mDBRefIO key case mdbref of Right
-- dbref -> return dbref
--
-- Left cache -> do tv<- newTVarIO DoNotExist let dbref= DBRef key
-- tv w <- mkWeakPtr dbref . Just $ deleteFromCache dbref H.update
-- cache key (CacheElem Nothing w) t <- timeInteger atomically $ do
-- applyTriggers [dbref] [Just x] --debug (before ++key)
-- writeTVar tv . Exist $ Elem x t t return dbref
--
-- Create the object passed as parameter (if it does not exist) and
-- return its reference in the STM monad. If an object with the same key
-- already exists, it is returned as is If not, the reference is created
-- with the new value. If you like to update in any case, use
-- getDBRef and writeDBRef combined
newDBRef :: (IResource a, Typeable a) => a -> STM (DBRef a)
-- | return the reference value. If it is not in the cache, it is fetched
-- from the database.
readDBRef :: (IResource a, Typeable a) => DBRef a -> STM (Maybe a)
-- | write in the reference a value The new key must be the same than the
-- old key of the previous object stored otherwise, an error law of
-- key conservation broken will be raised
--
-- WARNING: the value to be written in the DBRef must be fully evaluated.
-- Delayed evaluations at serialization time can cause inconsistencies in
-- the database. In future releases this will be enforced.
writeDBRef :: (IResource a, Typeable a) => DBRef a -> a -> STM ()
-- | delete the content of the DBRef form the cache and from permanent
-- storage
delDBRef :: (IResource a, Typeable a) => DBRef a -> STM ()
-- | An IResource instance that must be defined for every object being
-- cached. there are a set of implicit IResource instance trough utiliy
-- classes (See below)
class IResource a
keyResource :: IResource a => a -> String
readResourceByKey :: IResource a => String -> IO (Maybe a)
writeResource :: IResource a => a -> IO ()
delResource :: IResource a => a -> IO ()
-- | Empty resources: resources= Resources [] [] ()
resources :: Resources a ()
-- | This is the main function for the *Resource(s) 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 DBRefs The
-- Resources register returned by the user-defined function is
-- interpreted as such:
--
--
-- - toAdd: the content of this field will be added/updated to
-- the cache
-- - toDelete: the content of this field will be removed from
-- the cache and from permanent storage
-- - toReturn: the content of this field will be returned by
-- withSTMResources
--
--
-- WARNING: the values to be written must be fully evaluated. Delayed
-- evaluations at serialization time can cause inconsistencies in the
-- database. In future releases this will be enforced.
withSTMResources :: (IResource a, Typeable a) => [a] -> ([Maybe a] -> Resources a x) -> STM x
-- | Resources data definition used by withSTMResources
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
-- | to atomically add/modify many objects in the cache
withResources :: (IResource a, Typeable a) => [a] -> ([Maybe a] -> [a]) -> IO ()
-- | update of a single object in the cache
--
--
-- withResource r f= withResources [r] ([mr]-> [f mr])
--
withResource :: (IResource a, Typeable a) => a -> (Maybe a -> a) -> IO ()
getResources :: (IResource a, Typeable a) => [a] -> IO [Maybe a]
-- | to read a resource from the cache.
getResource :: (IResource a, Typeable a) => a -> IO (Maybe a)
-- | delete the list of resources from cache and from persistent storage.
deleteResources :: (IResource a, Typeable a) => [a] -> IO ()
-- | delete the resource from cache and from persistent storage.
-- deleteResource r= deleteResources [r]
deleteResource :: (IResource a, Typeable a) => a -> IO ()
-- | Add an user defined trigger to the list of triggers Trriggers are
-- called just before an object of the given type is created, modified or
-- deleted. The DBRef to the object and the new value is passed to the
-- trigger. The called trigger function has two parameters: the DBRef
-- being accesed (which still contains the old value), and the new value.
-- If the content of the DBRef is being deleted, the second parameter is
-- Nothing. if the DBRef contains Nothing, then the object is
-- being created
addTrigger :: (IResource a, Typeable a) => ((DBRef a) -> Maybe a -> STM ()) -> IO ()
-- | deletes the pointed object from the cache, not the database (see
-- delDBRef) useful for cache invalidation when the database is
-- modified by other process
flushDBRef :: (IResource a, Typeable a) => DBRef a -> STM ()
-- | drops the entire cache.
flushAll :: STM ()
type Cache = IORef (Ht, Integer)
-- | set the cache. this is useful for hot loaded modules that will update
-- an existing cache. Experimental
setCache :: Cache -> IO ()
-- | newCache creates a new cache. Experimental
newCache :: IO (Ht, Integer)
refcache :: Cache
-- | Force the atomic write of all cached objects modified since the last
-- save into permanent storage Cache writes allways save a coherent state
syncCache :: IO ()
-- | stablishes the procedures to call before and after saving with
-- syncCache, clearSyncCache or clearSyncCacheProc.
-- The postcondition of database persistence should be a commit.
setConditions :: IO () -> IO () -> IO ()
-- | Saves the unsaved elems of the cache Cache writes allways save a
-- coherent state delete some elems of the cache when the number of elems
-- > sizeObjects. The deletion depends on the check criteria.
-- defaultCheck is the one implemented
clearSyncCache :: (Integer -> Integer -> Integer -> Bool) -> Int -> IO ()
-- | return the total number of DBRefs in the cache. For debug purposes
-- This does not count the number of objects in the cache since many of
-- the DBRef may not have the pointed object loaded. Itś O(n).
numElems :: IO Int
-- | Start the thread that periodically call clearSyncCache to clean
-- and writes on the persistent storage. Otherwise, syncCache must
-- be invoked explicitly or no persistence will exist. Cache writes
-- allways save a coherent state
clearSyncCacheProc :: Int -> (Integer -> Integer -> Integer -> Bool) -> Int -> IO ThreadId
-- | ths is a default cache clearance check. It forces to drop from the
-- cache all the elems not accesed since half the time between now and
-- the last sync if it returns True, the object will be discarded from
-- the cache it is invoked when the cache size exceeds the number of
-- objects configured in clearSyncCacheProc or
-- clearSyncCache
defaultCheck :: Integer -> Integer -> Integer -> Bool
instance Ord (DBRef a)
instance Eq (DBRef a)
instance (IResource a, Typeable a) => Read (DBRef a)
instance Show (DBRef a)
-- | This module implements an experimental typed query language for TCache
-- build on pure haskell. It is minimally intrusive (no special data
-- definitions, no special syntax, no template haskell). It uses the same
-- register fields from the data definitions. Both for query conditions
-- and selections. It is executed in haskell, no external database
-- support is needed.
--
-- it includes
--
--
-- - A method for triggering the index-ation of the record
-- fields that you want to query
-- - A typed query language of these record fields, with:
-- - Relational operators: .==. .>. .>=.
-- .<=. .<. .&&. .||. to
-- compare fields with values (returning lists of DBRefs) or fields
-- between them, returning joins (lists of pairs of lists of DBRefs that
-- meet the condition).
-- - a select method to extract tuples of field values from the
-- DBRefs
-- - a recordsWith clause to extract entire registers
--
--
-- An example that register the owner and name fields fo the Car register
-- and the name of the Person register, create the Bruce register, return
-- the Bruce DBRef, create two Car registers with bruce as owner and
-- query for the registers with bruce as owner and its name alpabeticaly
-- higuer than "Bat mobile"
--
--
-- import Data.TCache
-- import Data.TCache.IndexQuery
-- import Data.TCache.FilePersistence
-- import Data.Typeable
--
-- data Person= Person {pname :: String} deriving (Show, Read, Eq, Typeable)
-- data Car= Car{owner :: DBRef Person , cname:: String} deriving (Show, Read, Eq, Typeable)
--
-- instance Indexable Person where key Person{pname= n} = "Person " ++ n
-- instance Indexable Car where key Car{cname= n} = "Car " ++ n
--
-- main = do
-- index owner
-- index pname
-- index cname
-- bruce <- atomically $ newDBRef $ Person "bruce"
-- atomically $ mapM_ newDBRef [Car bruce "Bat Mobile", Car bruce "Porsche"]
-- r <- atomically $ cname .==. "Porsche"
-- print r
-- r <- atomically $ select (cname, owner) $ (owner .==. bruce) .&&. (cname .>=. "Bat Mobile")
-- print r
--
--
-- Will produce:
--
--
-- [DBRef "Car Porsche"]
-- [("Porsche",DBRef "Person bruce")]
--
--
-- NOTES:
--
--
-- - the index is instance of Indexable and Serializable.
-- This can be used to persist in the user-defined storoage. If
-- Data.TCache.FilePersistence is included the indexes will be
-- written in files.
-- - The Join feature has not been properly tested
-- - Record fields are recognized by its type, so if we define two
-- record fields with the same type:
--
--
--
-- data Person = Person {name , surname :: String}
--
--
-- then a query for name .==. Bruce is
-- indistinguishable from surname .==. Bruce
--
-- Will return all the registers with surname Bruce as well. So if
-- two or more fields in a registers are to be indexed, they must have
-- different types.
module Data.TCache.IndexQuery
-- | Register a trigger for indexing the values of the field passed as
-- parameter. the indexed field can be used to perform relational-like
-- searches
index :: Queriable reg a => (reg -> a) -> IO ()
-- | implement the relational-like operators, operating on record fields
class RelationOps field1 field2 res | field1 field2 -> res
(.==.) :: RelationOps field1 field2 res => field1 -> field2 -> STM res
(.>.) :: RelationOps field1 field2 res => field1 -> field2 -> STM res
(.>=.) :: RelationOps field1 field2 res => field1 -> field2 -> STM res
(.<=.) :: RelationOps field1 field2 res => field1 -> field2 -> STM res
(.<.) :: RelationOps field1 field2 res => field1 -> field2 -> STM res
recordsWith :: (IResource a, Typeable a) => STM [DBRef a] -> STM [a]
(.&&.) :: SetOperations set set' setResult => STM set -> STM set' -> STM setResult
(.||.) :: SetOperations set set' setResult => STM set -> STM set' -> STM setResult
class Select selector a res | selector a -> res
select :: Select selector a res => selector -> a -> res
instance [incoherent] Typeable2 Index
instance [incoherent] Show a => Show (Index reg a)
instance [incoherent] (Typeable reg, IResource reg, Typeable reg', IResource reg', Select (reg -> a) (STM [DBRef reg]) (STM [a]), Select (reg' -> b) (STM [DBRef reg']) (STM [b])) => Select (reg -> a, reg' -> b) (STM (JoinData reg reg')) (STM [([a], [b])])
instance [incoherent] (Typeable reg, IResource reg, Select (reg -> a) (STM [DBRef reg]) (STM [a]), Select (reg -> b) (STM [DBRef reg]) (STM [b]), Select (reg -> c) (STM [DBRef reg]) (STM [c]), Select (reg -> d) (STM [DBRef reg]) (STM [d])) => Select (reg -> a, reg -> b, reg -> c, reg -> d) (STM [DBRef reg]) (STM [(a, b, c, d)])
instance [incoherent] (Typeable reg, IResource reg, Select (reg -> a) (STM [DBRef reg]) (STM [a]), Select (reg -> b) (STM [DBRef reg]) (STM [b]), Select (reg -> c) (STM [DBRef reg]) (STM [c])) => Select (reg -> a, reg -> b, reg -> c) (STM [DBRef reg]) (STM [(a, b, c)])
instance [incoherent] (Typeable reg, IResource reg, Select (reg -> a) (STM [DBRef reg]) (STM [a]), Select (reg -> b) (STM [DBRef reg]) (STM [b])) => Select (reg -> a, reg -> b) (STM [DBRef reg]) (STM [(a, b)])
instance [incoherent] (Typeable reg, IResource reg) => Select (reg -> a) (STM [DBRef reg]) (STM [a])
instance [incoherent] SetOperations (JoinData a a') [DBRef a'] (JoinData a a')
instance [incoherent] SetOperations [DBRef a] (JoinData a a') (JoinData a a')
instance [incoherent] SetOperations (JoinData a a') [DBRef a] (JoinData a a')
instance [incoherent] SetOperations [DBRef a] [DBRef a] [DBRef a]
instance [incoherent] (Queriable reg a, Queriable reg' a) => RelationOps (reg -> a) (reg' -> a) (JoinData reg reg')
instance [incoherent] Queriable reg a => RelationOps (reg -> a) a [DBRef reg]
instance [incoherent] (Typeable reg, Typeable a) => Indexable (Index reg a)
instance [incoherent] Queriable reg a => Serializable (Index reg a)
instance [incoherent] (IResource reg, Typeable reg, Read reg, Show reg, Show a, Read a, Ord a) => Read (Index reg a)
-- | Implements full text indexation (indexText) and text
-- search(contains), as an addition to the query language
-- implemented in IndexQuery it also can index the lists of
-- elements in a field (with indexList) so that it is possible to
-- ask for the registers that contains a given element in the given field
-- (with containsElem)
--
-- An example of full text search:
--
--
-- data Doc= Doc{title, body :: String} deriving (Read,Show, Typeable)
-- instance Indexable Doc where
-- key Doc{title=t}= t
--
-- instance Serializable Doc where
-- serialize= pack . show
-- deserialize= read . unpack
--
-- main= do
-- indexText body T.pack
-- let doc= Doc{title= title, body= hola que tal estamos}
-- rdoc <- atomically $ newDBRef doc
-- r1 <- atomically $ select title $ body contains hola que tal
-- print r1
--
-- atomically $ writeDBRef rdoc doc{ body= que tal}
-- r <- atomically $ select title $ body contains hola que tal
-- print r
-- if r1 == [title doc] then print OK else print FAIL
-- if r== [] then print OK else print FAIL
--
module Data.TCache.IndexText
-- | start a trigger to index the contents of a register field
indexText :: (IResource a, Typeable a, Typeable b) => (a -> b) -> (b -> Text) -> IO ()
indexList :: (IResource a, Typeable a, Typeable b) => (a -> b) -> (b -> [Text]) -> IO ()
-- | return the DBRefs whose fields include all the words of length three
-- or more in the requested text contents
contains :: (IResource a, Typeable a, Typeable b) => (a -> b) -> String -> STM [DBRef a]
containsElem :: (IResource a, Typeable a, Typeable b) => (a -> b) -> String -> STM [DBRef a]
instance Typeable IndexText
instance Indexable IndexText
instance Serializable IndexText
instance Read IndexText
instance Show IndexText