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


-- | STM transactions involving persistent storage
--   
--   While Haskell's STM monad allows you to execute code transactionally,
--   it does not allow you to persist the state on disk. This package
--   implements a persistent storage bridge that runs inside the already
--   existing STM monad.
@package persistent-stm
@version 0.1.0.0


-- | A scheme for adding persistence to Haskell's STM transactions. A
--   <tt><a>DBRef</a> a</tt> is like a <tt><a>TVar</a> (<a>Maybe</a>
--   a)</tt>, except that it exists (or not) in persistent storage as well
--   as in memory.
--   
--   The choice of persistent storage is up to the user, and is specified
--   with a <a>Persistence</a>. There is a default implementation called
--   <a>filePersistence</a> that uses files on disk. Note that
--   <a>filePersistence</a> 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 <a>Persistence</a> 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.
module PersistentSTM
data DB

-- | Opens a <a>DB</a> using the given <a>Persistence</a>. The caller
--   should guarantee that <a>closeDB</a> is called when the <a>DB</a> is
--   no longer needed.
openDB :: Persistence -> IO DB

-- | Closes a <a>DB</a>. When this call returns, all data will be written
--   to persistent storage, and the program can exit without possibly
--   losing data.
closeDB :: DB -> IO ()

-- | Runs an action with a <a>DB</a> open. The <a>DB</a> will be closed
--   when the action is finished. The <a>DB</a> value should not be used
--   after the action has returned.
withDB :: Persistence -> (DB -> IO a) -> IO a

-- | 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 <a>DBRef</a>s no longer need
--   to be retained once they are written to disk.
waitForMaxBacklog :: DB -> Int -> STM ()

-- | Atomically performs an STM transaction just like <a>atomically</a>,
--   but also waits for any changes it might have observed in the <a>DB</a>
--   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.
synchronously :: DB -> STM a -> IO a
data DBRef a

-- | A type class for things that can be stored in a DBRef. This is similar
--   to a serialization class like <a>Binary</a>, but reads have access to
--   the <a>DB</a> and the STM monad, which is important because it allows
--   for one <a>DBRef</a> to be stored inside the value of another. (In
--   this case, <a>decode</a> will call <a>getDBRef</a>.)
class Typeable a => DBStorable a
decode :: DBStorable a => DB -> ByteString -> STM a
decode :: (DBStorable a, Binary a) => DB -> ByteString -> STM a
encode :: DBStorable a => a -> ByteString
encode :: (DBStorable a, Binary a) => a -> ByteString

-- | Retrieves a <a>DBRef</a> from a <a>DB</a> for the given key. Throws an
--   exception if the <a>DBRef</a> requested has a different type from a
--   previous time the key was used in this process, or if a serialized
--   value in persistent storage cannot be parsed.
getDBRef :: forall a. DBStorable a => DB -> String -> STM (DBRef a)

-- | Gets the value stored in a <a>DBRef</a>. The value is <tt><a>Just</a>
--   x</tt> if <tt>x</tt> was last value stored in the database using this
--   key, or <a>Nothing</a> if there is no value stored in the database.
readDBRef :: DBRef a -> STM (Maybe a)

-- | Updates the value stored in a <a>DBRef</a>. The update will be
--   persisted to storage soon, but not synchronously.
writeDBRef :: DBStorable a => DBRef a -> a -> STM ()

-- | Deletes the value stored in a <a>DBRef</a>. The delete will be
--   persisted to storage soon, but not synchronously.
deleteDBRef :: DBStorable a => DBRef a -> STM ()

-- | A strategy for persisting values from <a>DBRef</a> to some persistent
--   storage. The <a>filePersistence</a> implementation is provided as a
--   quick way to get started, but note the weaknesses in its
--   documentation.
--   
--   A <a>Persistence</a> can read one value at a time, but should be able
--   to atomically write/delete an entire set of keys at once, preferably
--   atomically.
data Persistence
Persistence :: (String -> IO (Maybe ByteString)) -> (Map String (Maybe ByteString) -> IO ()) -> IO () -> Persistence

-- | Read a single value from persistent storage. Return the serialized
--   representation if it exists, and Nothing otherwise.
[persistentRead] :: Persistence -> String -> IO (Maybe ByteString)

-- | Write (for <a>Just</a> values) or delete (for <a>Nothing</a> values)
--   an entire set of values to persistent storage. The values should
--   ideally be written atomically, and if they are not then the
--   implementation will be vulnerable to inconsistent data and corruption
--   if the process is suddenly terminated.
[persistentWrite] :: Persistence -> Map String (Maybe ByteString) -> IO ()

-- | Perform any cleanup that is needed after the <a>DB</a> is closed. This
--   can include releasing locks, for example.
[persistentFinish] :: Persistence -> IO ()

-- | A simple <a>Persistence</a> 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 <a>Persistence</a> for most applications.
filePersistence :: FilePath -> IO Persistence
instance GHC.Classes.Eq (PersistentSTM.DBRef a)
instance GHC.Classes.Ord (PersistentSTM.DBRef a)
instance GHC.Show.Show (PersistentSTM.DBRef a)
instance PersistentSTM.DBStorable a => PersistentSTM.DBStorable (PersistentSTM.DBRef a)
instance PersistentSTM.DBStorable ()
instance PersistentSTM.DBStorable GHC.Types.Bool
instance PersistentSTM.DBStorable GHC.Types.Char
instance PersistentSTM.DBStorable GHC.Types.Double
instance PersistentSTM.DBStorable GHC.Types.Float
instance PersistentSTM.DBStorable GHC.Types.Int
instance PersistentSTM.DBStorable GHC.Int.Int8
instance PersistentSTM.DBStorable GHC.Int.Int16
instance PersistentSTM.DBStorable GHC.Int.Int32
instance PersistentSTM.DBStorable GHC.Int.Int64
instance PersistentSTM.DBStorable GHC.Integer.Type.Integer
instance PersistentSTM.DBStorable GHC.Natural.Natural
instance PersistentSTM.DBStorable GHC.Types.Ordering
instance PersistentSTM.DBStorable GHC.Types.Word
instance PersistentSTM.DBStorable GHC.Word.Word8
instance PersistentSTM.DBStorable GHC.Word.Word16
instance PersistentSTM.DBStorable GHC.Word.Word32
instance PersistentSTM.DBStorable GHC.Word.Word64
instance PersistentSTM.DBStorable Data.ByteString.Internal.ByteString
instance PersistentSTM.DBStorable Data.ByteString.Lazy.Internal.ByteString
instance PersistentSTM.DBStorable Data.ByteString.Short.Internal.ShortByteString
instance PersistentSTM.DBStorable a => PersistentSTM.DBStorable [a]