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

DBRefs are persistent cached database references in the STM monad with read/write primitives, so the traditional syntax of Haskell STM references can be used for interfacing with databases. As expected, the DBRefs are transactional, because they operate in the STM monad.

DBRefs are references to cached database objects. A DBRef is associated with its referred object and its key Since DBRefs are serializable, they can be elements of mutable objects. They could point to other mutable objects and so on, so DBRefs can act as hardwired relations from mutable objects to other mutable objects in the database/cache. their referred objects are loaded, saved and flused to and from the cache automatically depending on the cache handling policies and the access needs

DBRefs are univocally identified by its pointed object keys, so they can be compared, ordered and so on. The creation of a DBRef, trough getDBRef is pure. This permits an efficient lazy marshalling of registers with references, such are indexes when are queried for some fields but not others.

Example: Car registers have references to Person regiters

data Person= Person {pname :: String} deriving  (Show, Read, Eq, Typeable)
data Car= Car{owner :: DBRef Person , cname:: String} deriving (Show, Read, Eq, Typeable)

Here the Car register point to the Person register trough the owner field

To permit persistence and being refered with DBRefs, define the Indexable instance for these two register types:

instance Indexable Person where key Person{pname= n} = Person  ++ n
instance Indexable Car where key Car{cname= n} = Car  ++ n

Now we create a DBRef to a Person whose name is "Bruce"

>>> let bruce =   getDBRef . key $ Person "Bruce" :: DBRef Person

>>> show bruce
>"DBRef \"Person bruce\""

>>> atomically (readDBRef bruce)
>Nothing

getDBRef is pure and creates the reference, but not the referred object; To create both the reference and the DBRef, use newDBRef. Lets create two Car's and its two Car DBRefs with bruce as owner:

>>> cars <- atomically $  mapM newDBRef [Car bruce "Bat Mobile", Car bruce "Porsche"]

>>> print cars
>[DBRef "Car Bat Mobile",DBRef "Car Porsche"]

>>> carRegs<- atomically $ mapM readDBRef cars
> [Just (Car {owner = DBRef "Person bruce", cname = "Bat Mobile"})
> ,Just (Car {owner = DBRef "Person bruce", cname = "Porsche"})]

try to write with writeDBRef

>>> atomically . writeDBRef bruce $ Person "Other"
>*** Exception: writeDBRef: law of key conservation broken: old , new= Person bruce , Person Other

DBRef's can not be written with objects of different keys

>>> atomically . writeDBRef bruce $ Person "Bruce"

>>> let Just carReg1= head carRegs

now from the Car register it is possible to recover the owner's register

>>> atomically $ readDBRef ( owner carReg1)
>Just (Person {pname = "bruce"})

DBRefs, once the pointed cached object is looked up in the cache and found at creation, they does not perform any further cache lookup afterwards, so reads and writes from/to DBRefs are faster than *Resource(s) calls, which perform lookups everytime in the cache

DBRef's and *Resource(s) primitives are completely interoperable. The latter operate implicitly with DBRef's

cached objects must be instances of IResource. Such instances can be implicitly derived trough auxiliary clasess for file persistence

Operations with DBRef's can be performed implicitly with the "traditional" TCache operations available in older versions.

In this example "buy" is a transaction where the user buy an item. The spent amount is increased and the stock of the product is decreased:

data  Data=   User{uname::String, uid::String, spent:: Int} |
              Item{iname::String, iid::String, price::Int, stock::Int}
              deriving (Read, Show)

instance Indexable Data where
        key   User{uid=id}= id
        key   Item{iid=id}= id

user buy item=  withResources[user,item] buyIt
 where
    buyIt[Just us,Just it]
       | stock it > 0= [us',it']
       | otherwise   = error "stock is empty for this product"
      where
       us'= us{spent=spent us + price it}
       it'= it{stock= stock it-1}
    buyIt _ = error "either the user or the item (or both) does not exist"

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

Example:

every time a car is added, or deleted, the owner's list is updated this is done by the user defined trigger addCar

 addCar pcar (Just(Car powner _ )) = addToOwner powner pcar
 addCar pcar Nothing  = readDBRef pcar >>= (Just car)-> deleteOwner (owner car) pcar

addToOwner powner pcar=do
    Just owner <- readDBRef powner
    writeDBRef powner owner{cars= nub $ pcar : cars owner}

deleteOwner powner pcar= do
   Just owner <- readDBRef powner
   writeDBRef powner owner{cars= delete  pcar $ cars owner}

main= do
    addTrigger addCar
    putStrLn "create bruce's register with no cars"
    bruce <- atomically newDBRef $ Person "Bruce" []
    putStrLn add two car register with "bruce" as owner using the reference to the bruces register
    let newcars= [Car bruce "Bat Mobile" , Car bruce "Porsche"]
    insert newcars
    Just bruceData <- atomically $ readDBRef bruce
    putStrLn the trigger automatically updated the car references of the Bruce register
    print . length $ cars bruceData
    print bruceData

produces:

gives:

 main
 2
 Person {pname = "Bruce", cars = [DBRef "Car Porsche",DBRef "Car Bat Mobile"]}