| Portability | non-portable (requires STM) |
|---|---|
| Stability | experimental |
| Maintainer | Peter Robinson <thaldyron@gmail.com> |
Control.Concurrent.TBox
Contents
Description
An abstract interface for transactional variables with IO hooks.
- class TBox t k a where
- new :: k -> a -> AdvSTM (t k a)
- newIO :: k -> a -> IO (t k a)
- newEmpty :: k -> AdvSTM (t k a)
- newEmptyIO :: k -> IO (t k a)
- writeSTM :: t k a -> a -> AdvSTM ()
- writeIO :: t k a -> a -> IO ()
- readSTM :: t k a -> AdvSTM (Maybe a)
- readIO :: t k a -> IO (Maybe a)
- clearSTM :: t k a -> AdvSTM ()
- clearIO :: t k a -> IO ()
- isDirty :: t k a -> AdvSTM Bool
- setDirty :: t k a -> Bool -> AdvSTM ()
- read :: TBox t k a => t k a -> AdvSTM (Maybe a)
- write :: TBox t k a => t k a -> a -> AdvSTM ()
- clear :: TBox t k a => t k a -> AdvSTM ()
- isEmpty :: TBox t k a => t k a -> AdvSTM Bool
- isEmptyNotDirty :: TBox t k a => t k a -> AdvSTM Bool
TBox type class
An instance of TBox is a (Adv)STM variable that might contain a value of
some type a. In contrast to a plain 'TVar (Maybe a)', a
TBox has IO hooks that are executed transparently on writes and reads,
which makes it particularly suitable for implementing a persistent and thread-safe storage.
The type variable k can be used to provide additional storage information, e.g.,
a filepath.
Important: Note that the read/write functions of this type class, i.e.,
readIO, readSTM, writeIO, writeSTM, clearIO, clearSTM should
only be used to derive new
instances and do not serve to modify the state of a TBox.
The interface defined in module TBox.Operations provides
operations on TBoxs that guarantee consistency.
See the module Control.Concurrent.TFile for a sample instance.
Methods
new :: k -> a -> AdvSTM (t k a)Source
Takes a key and an initial value
newIO :: k -> a -> IO (t k a)Source
Takes a key and an initial value. Has a default implementation.
newEmpty :: k -> AdvSTM (t k a)Source
Takes a key and returns an empty t
newEmptyIO :: k -> IO (t k a)Source
Takes a key and returns an empty t. Has a default implementation.
writeSTM :: t k a -> a -> AdvSTM ()Source
Used in TBox.write.
writeIO :: t k a -> a -> IO ()Source
Used in TBox.write during the commit phase.
Is guaranteed to be executed exactly once iff the transaction commits.
readSTM :: t k a -> AdvSTM (Maybe a)Source
Used in TBox.read
readIO :: t k a -> IO (Maybe a)Source
Used in TBox.read when retrying the transaction, which happens when the
TBox has been marked "dirty".
Note: Might be executed multiple times for the
same TBox in a single transaction. See unsafeRetryWith.
clearSTM :: t k a -> AdvSTM ()Source
Used in TBox.clear
clearIO :: t k a -> IO ()Source
Used in TBox.clear during the commit phase.
Is guaranteed to be executed exactly once iff the transaction commits.
isDirty :: t k a -> AdvSTM BoolSource
setDirty :: t k a -> Bool -> AdvSTM ()Source
Change the "dirty" status of the TBox.
Operations on a TBox
read :: TBox t k a => t k a -> AdvSTM (Maybe a)Source
If the TBox is dirty, this retries the transaction and
rereads the content using readIO in a separate thread.
Otherwise it simply returns the result of readSTM.
Note: Depending on the instance implementation, careless
use of setDirty and read in the same transaction might lead
to nonterminating retry loops.