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


-- | Transactional variables with IO hooks
--   
--   (to be expanded...)
--   
--   This package provides transactional variables with IO hooks. See
--   module <a>Control.Concurrent.TFile</a> for a concrete instance.
--   
--   Feedback appreciated!
@package tbox
@version 0.0.0


-- | The type class <a>TBox</a>.
module Control.Concurrent.TBox.Class

-- | An instance of <a>TBox</a> is a (Adv)STM variable that might contain a
--   value of some type a. In contrast to a plain TVar, a <a>TBox</a> has
--   IO hooks that are executed transparently on updates and reads. The
--   functions of the type class shouldn't be exposed directly but should
--   be used via the interface defined in the module TBox.Operations.
--   
--   See the module TFile for a concrete instantiation.
class TBox t a
writeSTM :: (TBox t a) => t a -> a -> AdvSTM ()
writeIO :: (TBox t a) => t a -> a -> IO ()
readSTM :: (TBox t a) => t a -> AdvSTM (Maybe a)
readIO :: (TBox t a) => t a -> IO (Maybe a)
deleteSTM :: (TBox t a) => t a -> AdvSTM ()
deleteIO :: (TBox t a) => t a -> IO ()
isDirty :: (TBox t a) => t a -> AdvSTM Bool
setDirty :: (TBox t a) => t a -> Bool -> AdvSTM ()


-- | Operations on instances of <a>TBox</a>.
module Control.Concurrent.TBox.Operations

-- | Deletes the content.
delete :: (TBox t a) => t a -> AdvSTM ()

-- | Writes the new content.
write :: (TBox t a) => t a -> a -> AdvSTM ()

-- | If the TBox is dirty, this retries the transaction and rereads the
--   content using <a>readIO</a> in a separate thread. Otherwise it simply
--   returns the result of <a>readSTM</a>.
--   
--   Note: Depending on the implementation, careless use of <a>setDirty</a>
--   and <a>read</a> in the same transaction might lead to nonterminating
--   retry loops.
read :: (TBox t a) => t a -> AdvSTM (Maybe a)

-- | Returns <a>True</a> iff the <a>TBox</a> is empty.
isEmpty :: (TBox t a) => t a -> AdvSTM Bool


-- | A transactional variable that writes its content to a file on each
--   update.
--   
--   This module should be imported qualified.
module Control.Concurrent.TFile

-- | A transactional variable that writes its content to a file on each
--   update.
--   
--   <ul>
--   <li>The updated memory content of the TFile is not visible to other
--   threads until the file has been written successfully.</li>
--   <li>If the <a>TFile</a> is "dirty", the content is (re)read from the
--   file on the next <a>read</a>.</li>
--   </ul>
data TFile a

-- | Constructs an initially empty <a>TFile</a> that is marked dirty. That
--   means, on the next <a>read</a>, the contents of the provided file (if
--   it exists) will be loaded into the <a>TFile</a>.
newEmptyIO :: (Binary a) => FilePath -> IO (TFile a)
newIO :: (Binary a) => FilePath -> a -> IO (TFile a)
new :: (Binary a) => FilePath -> a -> AdvSTM (TFile a)

-- | If the TBox is dirty, this retries the transaction and rereads the
--   content using <a>readIO</a> in a separate thread. Otherwise it simply
--   returns the result of <a>readSTM</a>.
--   
--   Note: Depending on the implementation, careless use of <a>setDirty</a>
--   and <a>read</a> in the same transaction might lead to nonterminating
--   retry loops.
read :: (TBox t a) => t a -> AdvSTM (Maybe a)

-- | Writes the new content.
write :: (TBox t a) => t a -> a -> AdvSTM ()

-- | Deletes the content.
delete :: (TBox t a) => t a -> AdvSTM ()

-- | Returns <a>True</a> iff the <a>TBox</a> is empty.
isEmpty :: (TBox t a) => t a -> AdvSTM Bool
instance Typeable1 TFile
instance (Binary a) => TBox TFile a


-- | An abstract interface for transactional variables with IO hooks.
module Control.Concurrent.TBox

-- | An instance of <a>TBox</a> is a (Adv)STM variable that might contain a
--   value of some type a. In contrast to a plain TVar, a <a>TBox</a> has
--   IO hooks that are executed transparently on updates and reads. The
--   functions of the type class shouldn't be exposed directly but should
--   be used via the interface defined in the module TBox.Operations.
--   
--   See the module TFile for a concrete instantiation.
class TBox t a
writeSTM :: (TBox t a) => t a -> a -> AdvSTM ()
writeIO :: (TBox t a) => t a -> a -> IO ()
readSTM :: (TBox t a) => t a -> AdvSTM (Maybe a)
readIO :: (TBox t a) => t a -> IO (Maybe a)
deleteSTM :: (TBox t a) => t a -> AdvSTM ()
deleteIO :: (TBox t a) => t a -> IO ()
isDirty :: (TBox t a) => t a -> AdvSTM Bool
setDirty :: (TBox t a) => t a -> Bool -> AdvSTM ()

-- | If the TBox is dirty, this retries the transaction and rereads the
--   content using <a>readIO</a> in a separate thread. Otherwise it simply
--   returns the result of <a>readSTM</a>.
--   
--   Note: Depending on the implementation, careless use of <a>setDirty</a>
--   and <a>read</a> in the same transaction might lead to nonterminating
--   retry loops.
read :: (TBox t a) => t a -> AdvSTM (Maybe a)

-- | Writes the new content.
write :: (TBox t a) => t a -> a -> AdvSTM ()

-- | Deletes the content.
delete :: (TBox t a) => t a -> AdvSTM ()

-- | Returns <a>True</a> iff the <a>TBox</a> is empty.
isEmpty :: (TBox t a) => t a -> AdvSTM Bool