| Safe Haskell | None |
|---|---|
| Language | Haskell2010 |
PersistentSTM
Description
A scheme for adding persistence to Haskell's STM transactions. A DBRef
aTVar (Maybe a)
The choice of persistent storage is up to the user, and is specified with a
Persistence. There is a default implementation called filePersistence
that uses files on disk. Note that filePersistence doesn't guarantee
transactional atomicity in the presence of sudden termination of the process,
such as in a power outage or system crash. Therefore, for serious use,
it's recommended that you use a different Persistence implementation based
on a storage layer with stronger transactional guarantees.
For this scheme to work at all, this process must be the only entity to access the persistent storage. You may not even use a single-writer, multiple-reader architecture, because consistency guarantees for reads, as well, depend on all writes happening in the current process.
Synopsis
- data DB
- openDB :: Persistence -> IO DB
- closeDB :: DB -> IO ()
- withDB :: Persistence -> (DB -> IO a) -> IO a
- waitForMaxBacklog :: DB -> Int -> STM ()
- synchronously :: DB -> STM a -> IO a
- data DBRef a
- class Typeable a => DBStorable a where
- decode :: DB -> ByteString -> STM a
- encode :: a -> ByteString
- getDBRef :: forall a. DBStorable a => DB -> String -> STM (DBRef a)
- readDBRef :: DBRef a -> STM (Maybe a)
- writeDBRef :: DBStorable a => DBRef a -> a -> STM ()
- deleteDBRef :: DBStorable a => DBRef a -> STM ()
- data Persistence = Persistence {
- persistentRead :: String -> IO (Maybe ByteString)
- persistentWrite :: Map String (Maybe ByteString) -> IO ()
- persistentFinish :: IO ()
- filePersistence :: FilePath -> IO Persistence
Documentation
openDB :: Persistence -> IO DB Source #
Opens a DB using the given Persistence. The caller should guarantee
that closeDB is called when the DB is no longer needed.
closeDB :: DB -> IO () Source #
Closes a DB. When this call returns, all data will be written to
persistent storage, and the program can exit without possibly losing data.
waitForMaxBacklog :: DB -> Int -> STM () Source #
Check that there are at most the given number of queued writes to the
database, and retries the transaction if so. Adding this to the beginning of
your transactions can help prevent writes from falling too far behind the
live data. Prioritizing writes this way can also reduce memory usage,
because unreachable DBRefs no longer need to be retained once they are
written to disk.
synchronously :: DB -> STM a -> IO a Source #
Atomically performs an STM transaction just like atomically, but also
waits for any changes it might have observed in the DB to be written to
persistent storage before returning. This guarantees that a transaction
whose results were observed will not be rolled back if the program crashes.
class Typeable a => DBStorable a where Source #
A type class for things that can be stored in a DBRef. This is similar to
a serialization class like Binary, but reads have access to the DB and
the STM monad, which is important because it allows for one DBRef to be
stored inside the value of another. (In this case, decode will call
getDBRef.)
Minimal complete definition
Nothing
Methods
decode :: DB -> ByteString -> STM a Source #
encode :: a -> ByteString Source #
default encode :: Binary a => a -> ByteString Source #
Instances
writeDBRef :: DBStorable a => DBRef a -> a -> STM () Source #
Updates the value stored in a DBRef. The update will be persisted to
storage soon, but not synchronously.
deleteDBRef :: DBStorable a => DBRef a -> STM () Source #
Deletes the value stored in a DBRef. The delete will be persisted to
storage soon, but not synchronously.
data Persistence Source #
A strategy for persisting values from DBRef to some persistent storage.
The filePersistence implementation is provided as a quick way to get
started, but note the weaknesses in its documentation.
A Persistence can read one value at a time, but should be able to atomically
write/delete an entire set of keys at once, preferably atomically.
Constructors
| Persistence | |
Fields
| |
filePersistence :: FilePath -> IO Persistence Source #
A simple Persistence that stores data in a directory in the local
filesystem. This is an easy way to get started. However, note that because
writes are not atomic, your data can be corrupted during a crash or power
outage. For this reason, it's recommended that you use a different
Persistence for most applications.