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


-- | Add ACID guarantees to any serializable Haskell data structure.
--   
--   Use regular Haskell data structures as your database and get stronger
--   ACID guarantees than most RDBMS offer.
@package acid-state
@version 0.16.1.4

module Data.Acid.CRC
crc16 :: ByteString -> Word16

module Data.Acid.Archive

-- | A bytestring that represents an entry in an archive.
type Entry = ByteString

-- | Result of unpacking an archive. This is essentially a list of
--   <a>Entry</a>, but may terminate in <a>Fail</a> if the archive format
--   is incorrect.
data Entries
Done :: Entries
Next :: Entry -> Entries -> Entries
Fail :: String -> Entries
putEntries :: [Entry] -> Builder
packEntries :: [Entry] -> ByteString
readEntries :: ByteString -> Entries

-- | Convert <a>Entries</a> to a normal list, calling <a>error</a> if there
--   was a failure in unpacking the archive.
entriesToList :: Entries -> [Entry]

-- | Convert <a>Entries</a> to a normal list, silently ignoring a failure
--   to unpack the archive and instead returning a truncated list.
entriesToListNoFail :: Entries -> [Entry]

-- | Interface for the lowest level of the serialisation layer, which
--   handles packing lists of <a>Entry</a> elements (essentially just
--   bytestrings) into a single bytestring, perhaps with error-checking.
--   
--   Any <tt><a>Archiver</a>{<a>archiveWrite</a>, <a>archiveRead</a>}</tt>
--   must satisfy the round-trip property:
--   
--   <pre>
--   forall xs . entriesToList (archiveRead (archiveWrite xs)) == xs
--   </pre>
--   
--   Moreover, <a>archiveWrite</a> must be a monoid homomorphism, so that
--   concatenating archives is equivalent to concatenating the lists of
--   entries that they represent:
--   
--   <pre>
--   archiveWrite [] == empty
--   forall xs ys . archiveWrite xs &lt;&gt; archiveWrite ys == archiveWrite (xs ++ ys)
--   </pre>
data Archiver
Archiver :: ([Entry] -> ByteString) -> (ByteString -> Entries) -> Archiver

-- | Pack a list of entries into a bytestring.
[archiveWrite] :: Archiver -> [Entry] -> ByteString

-- | Unpack a bytestring as a list of <a>Entries</a>, including the
--   possibility of failure if the format is invalid.
[archiveRead] :: Archiver -> ByteString -> Entries

-- | Standard (and historically the only) implementation of the
--   <a>Archiver</a> interface. This represents each entry in the following
--   format:
--   
--   <pre>
--   | entry length | crc16   | entry   |
--   | 8 bytes      | 2 bytes | n bytes |
--   </pre>
defaultArchiver :: Archiver
instance GHC.Internal.Show.Show Data.Acid.Archive.Entries


-- | Low-level controls for transaction-based state changes. This module
--   defines structures and tools for running state modifiers indexed
--   either by an Method or a serialized Method. This module should rarely
--   be used directly although the <a>Method</a> class is needed when
--   defining events manually.
--   
--   The term 'Event' is loosely used for transactions with ACID
--   guarantees. 'Method' is loosely used for state operations without ACID
--   guarantees
module Data.Acid.Core

-- | The control structure at the very center of acid-state. This module
--   provides access to a mutable state through methods. No efforts towards
--   durability, checkpointing or sharding happens at this level. Important
--   things to keep in mind in this module: * We don't distinguish between
--   updates and queries. * We allow direct access to the core state as
--   well as through events.
data Core st

-- | The basic Method class. Each Method has an indexed result type and a
--   unique tag.
class Method ev where {
    type MethodResult ev;
    type MethodState ev;
}
methodTag :: Method ev => ev -> Tag
($dmmethodTag) :: (Method ev, Typeable ev) => ev -> Tag

-- | Method container structure that hides the exact type of the method.
data MethodContainer st
[Method] :: forall method. Method method => MethodBody method -> MethodSerialiser method -> MethodContainer (MethodState method)
type Tagged a = (Tag, a)

-- | Construct a new Core using an initial state and a list of Methods.
mkCore :: [MethodContainer st] -> st -> IO (Core st)

-- | Mark Core as closed. Any subsequent use will throw an exception.
closeCore :: Core st -> IO ()

-- | Access the state and then mark the Core as closed. Any subsequent use
--   will throw an exception.
closeCore' :: Core st -> (st -> IO ()) -> IO ()

-- | Modify the state component. The resulting state is ensured to be in
--   WHNF.
modifyCoreState :: Core st -> (st -> IO (st, a)) -> IO a

-- | Modify the state component. The resulting state is ensured to be in
--   WHNF.
modifyCoreState_ :: Core st -> (st -> IO st) -> IO ()

-- | Access the state component.
withCoreState :: Core st -> (st -> IO a) -> IO a

-- | Find the state action that corresponds to an in-memory method.
lookupHotMethod :: Method method => MethodMap (MethodState method) -> method -> State (MethodState method) (MethodResult method)

-- | Find the state action and serialiser that correspond to an in-memory
--   method.
lookupHotMethodAndSerialiser :: Method method => MethodMap (MethodState method) -> method -> (State (MethodState method) (MethodResult method), MethodSerialiser method)

-- | Find the state action that corresponds to a tagged and serialized
--   method.
lookupColdMethod :: Core st -> Tagged ByteString -> State st ByteString

-- | Apply an in-memory method to the state.
runHotMethod :: Method method => Core (MethodState method) -> method -> IO (MethodResult method)

-- | Execute a method as given by a type identifier and an encoded string.
--   The exact format of the encoded string depends on the type identifier.
--   Results are encoded and type tagged before they're handed back out.
--   This function is used when running events from a log-file or from
--   another server. Events that originate locally are most likely executed
--   with the faster <a>runHotMethod</a>.
runColdMethod :: Core st -> Tagged ByteString -> IO ByteString

-- | Collection of Methods indexed by a Tag.
type MethodMap st = Map Tag MethodContainer st

-- | Construct a <a>MethodMap</a> from a list of Methods using their
--   associated tag.
mkMethodMap :: [MethodContainer st] -> MethodMap st

-- | Interface for (de)serialising values of type <tt>a</tt>.
--   
--   A <tt><a>Serialiser</a> { <a>serialiserEncode</a>,
--   <a>serialiserDecode</a> }</tt> must satisfy the round-trip property:
--   
--   <pre>
--   forall x . serialiserDecode (serialiserEncode x) == Right x
--   </pre>
data Serialiser a
Serialiser :: (a -> ByteString) -> (ByteString -> Either String a) -> Serialiser a

-- | Serialise a value to a bytestring.
[serialiserEncode] :: Serialiser a -> a -> ByteString

-- | Deserialise a value, generating a string error message on failure.
[serialiserDecode] :: Serialiser a -> ByteString -> Either String a

-- | Default implementation of <a>Serialiser</a> interface using
--   <a>SafeCopy</a>.
safeCopySerialiser :: SafeCopy a => Serialiser a

-- | Interface for (de)serialising a method, namely <a>Serialiser</a>s for
--   its arguments type and its result type.
data MethodSerialiser method
MethodSerialiser :: Serialiser method -> Serialiser (MethodResult method) -> MethodSerialiser method
[methodSerialiser] :: MethodSerialiser method -> Serialiser method
[resultSerialiser] :: MethodSerialiser method -> Serialiser (MethodResult method)

-- | Default implementation of <a>MethodSerialiser</a> interface using
--   <a>SafeCopy</a>.
safeCopyMethodSerialiser :: (SafeCopy method, SafeCopy (MethodResult method)) => MethodSerialiser method

-- | Encode the arguments of a method using the given serialisation
--   strategy.
encodeMethod :: MethodSerialiser method -> method -> ByteString

-- | Decode the arguments of a method using the given serialisation
--   strategy.
decodeMethod :: MethodSerialiser method -> ByteString -> Either String method

-- | Encode the result of a method using the given serialisation strategy.
encodeResult :: MethodSerialiser method -> MethodResult method -> ByteString

-- | Decode the result of a method using the given serialisation strategy.
decodeResult :: MethodSerialiser method -> ByteString -> Either String (MethodResult method)


-- | Common structures used by the various backends (local, memory).
module Data.Acid.Common
class IsAcidic st
acidEvents :: IsAcidic st => [Event st]

-- | Context monad for Update events.
newtype Update st a
Update :: State st a -> Update st a
[unUpdate] :: Update st a -> State st a

-- | Context monad for Query events.
newtype Query st a
Query :: Reader st a -> Query st a
[unQuery] :: Query st a -> Reader st a

-- | Run a query in the Update Monad.
liftQuery :: Query st a -> Update st a

-- | Events return the same thing as Methods. The exact type of
--   <a>EventResult</a> depends on the event.
type EventResult ev = MethodResult ev
type EventState ev = MethodState ev

-- | We distinguish between events that modify the state and those that do
--   not.
--   
--   UpdateEvents are executed in a MonadState context and have to be
--   serialized to disk before they are considered durable.
--   
--   QueryEvents are executed in a MonadReader context and obviously do not
--   have to be serialized to disk.
data Event st
[UpdateEvent] :: forall ev. UpdateEvent ev => (ev -> Update (EventState ev) (EventResult ev)) -> MethodSerialiser ev -> Event (MethodState ev)
[QueryEvent] :: forall ev. QueryEvent ev => (ev -> Query (EventState ev) (EventResult ev)) -> MethodSerialiser ev -> Event (MethodState ev)

-- | All UpdateEvents are also Methods.
class Method ev => UpdateEvent ev

-- | All QueryEvents are also Methods.
class Method ev => QueryEvent ev
eventsToMethods :: [Event st] -> [MethodContainer st]
instance GHC.Internal.Base.Applicative (Data.Acid.Common.Query st)
instance GHC.Internal.Base.Applicative (Data.Acid.Common.Update st)
instance GHC.Internal.Base.Functor (Data.Acid.Common.Query st)
instance GHC.Internal.Base.Functor (Data.Acid.Common.Update st)
instance Control.Monad.Reader.Class.MonadReader st (Data.Acid.Common.Query st)
instance Control.Monad.State.Class.MonadState st (Data.Acid.Common.Update st)
instance GHC.Internal.Base.Monad (Data.Acid.Common.Query st)
instance GHC.Internal.Base.Monad (Data.Acid.Common.Update st)

module Data.Acid.Abstract

-- | State container offering full ACID (Atomicity, Consistency, Isolation
--   and Durability) guarantees.
--   
--   <ul>
--   <li><i><tt>Atomicity</tt></i> State changes are all-or-nothing. This
--   is what you'd expect of any state variable in Haskell and AcidState
--   doesn't change that.</li>
--   <li><i><tt>Consistency</tt></i> No event or set of events will break
--   your data invariants.</li>
--   <li><i><tt>Isolation</tt></i> Transactions cannot interfere with each
--   other even when issued in parallel.</li>
--   <li><i><tt>Durability</tt></i> Successful transaction are guaranteed
--   to survive unexpected system shutdowns (both those caused by hardware
--   and software).</li>
--   </ul>
data AcidState st
AcidState :: (forall event. (UpdateEvent event, EventState event ~ st) => event -> IO (MVar (EventResult event))) -> (Tagged ByteString -> IO (MVar ByteString)) -> (forall event. (QueryEvent event, EventState event ~ st) => event -> IO (EventResult event)) -> (Tagged ByteString -> IO ByteString) -> IO () -> IO () -> IO () -> AnyState st -> AcidState st
[_scheduleUpdate] :: AcidState st -> forall event. (UpdateEvent event, EventState event ~ st) => event -> IO (MVar (EventResult event))
[scheduleColdUpdate] :: AcidState st -> Tagged ByteString -> IO (MVar ByteString)
[_query] :: AcidState st -> forall event. (QueryEvent event, EventState event ~ st) => event -> IO (EventResult event)
[queryCold] :: AcidState st -> Tagged ByteString -> IO ByteString
[createCheckpoint] :: AcidState st -> IO ()
[createArchive] :: AcidState st -> IO ()
[closeAcidState] :: AcidState st -> IO ()
[acidSubState] :: AcidState st -> AnyState st

-- | Issue an Update event and return immediately. The event is not durable
--   before the MVar has been filled but the order of events is honored.
--   The behavior in case of exceptions is exactly the same as for
--   <a>update</a>.
--   
--   If EventA is scheduled before EventB, EventA <i>will</i> be executed
--   before EventB:
--   
--   <pre>
--   do scheduleUpdate acid EventA
--      scheduleUpdate acid EventB
--      
--   </pre>
scheduleUpdate :: UpdateEvent event => AcidState (EventState event) -> event -> IO (MVar (EventResult event))

-- | Schedule multiple Update events and wait for them to be durable, but
--   throw away their results. This is useful for importing existing
--   datasets into an AcidState.
groupUpdates :: UpdateEvent event => AcidState (EventState event) -> [event] -> IO ()

-- | Issue an Update event and wait for its result. Once this call returns,
--   you are guaranteed that the changes to the state are durable. Events
--   may be issued in parallel.
--   
--   It's a run-time error to issue events that aren't supported by the
--   AcidState.
update :: UpdateEvent event => AcidState (EventState event) -> event -> IO (EventResult event)

-- | Same as <a>update</a> but lifted into any monad capable of doing IO.
update' :: (UpdateEvent event, MonadIO m) => AcidState (EventState event) -> event -> m (EventResult event)

-- | Issue a Query event and wait for its result. Events may be issued in
--   parallel.
query :: QueryEvent event => AcidState (EventState event) -> event -> IO (EventResult event)

-- | Same as <a>query</a> but lifted into any monad capable of doing IO.
query' :: (QueryEvent event, MonadIO m) => AcidState (EventState event) -> event -> m (EventResult event)
mkAnyState :: Typeable sub_st => sub_st st -> AnyState st
downcast :: (Typeable sub, Typeable st) => AcidState st -> sub st


-- | Home of the more specialized functions.
module Data.Acid.Advanced

-- | Issue an Update event and return immediately. The event is not durable
--   before the MVar has been filled but the order of events is honored.
--   The behavior in case of exceptions is exactly the same as for
--   <a>update</a>.
--   
--   If EventA is scheduled before EventB, EventA <i>will</i> be executed
--   before EventB:
--   
--   <pre>
--   do scheduleUpdate acid EventA
--      scheduleUpdate acid EventB
--      
--   </pre>
scheduleUpdate :: UpdateEvent event => AcidState (EventState event) -> event -> IO (MVar (EventResult event))

-- | Schedule multiple Update events and wait for them to be durable, but
--   throw away their results. This is useful for importing existing
--   datasets into an AcidState.
groupUpdates :: UpdateEvent event => AcidState (EventState event) -> [event] -> IO ()

-- | Same as <a>update</a> but lifted into any monad capable of doing IO.
update' :: (UpdateEvent event, MonadIO m) => AcidState (EventState event) -> event -> m (EventResult event)

-- | Same as <a>query</a> but lifted into any monad capable of doing IO.
query' :: (QueryEvent event, MonadIO m) => AcidState (EventState event) -> event -> m (EventResult event)

-- | The basic Method class. Each Method has an indexed result type and a
--   unique tag.
class Method ev where {
    type MethodResult ev;
    type MethodState ev;
}
methodTag :: Method ev => ev -> Tag
($dmmethodTag) :: (Method ev, Typeable ev) => ev -> Tag
class IsAcidic st
acidEvents :: IsAcidic st => [Event st]

-- | We distinguish between events that modify the state and those that do
--   not.
--   
--   UpdateEvents are executed in a MonadState context and have to be
--   serialized to disk before they are considered durable.
--   
--   QueryEvents are executed in a MonadReader context and obviously do not
--   have to be serialized to disk.
data Event st
[UpdateEvent] :: forall ev. UpdateEvent ev => (ev -> Update (EventState ev) (EventResult ev)) -> MethodSerialiser ev -> Event (MethodState ev)
[QueryEvent] :: forall ev. QueryEvent ev => (ev -> Query (EventState ev) (EventResult ev)) -> MethodSerialiser ev -> Event (MethodState ev)

-- | Default implementation of <a>Serialiser</a> interface using
--   <a>SafeCopy</a>.
safeCopySerialiser :: SafeCopy a => Serialiser a

-- | Default implementation of <a>MethodSerialiser</a> interface using
--   <a>SafeCopy</a>.
safeCopyMethodSerialiser :: (SafeCopy method, SafeCopy (MethodResult method)) => MethodSerialiser method

-- | Standard (and historically the only) implementation of the
--   <a>Archiver</a> interface. This represents each entry in the following
--   format:
--   
--   <pre>
--   | entry length | crc16   | entry   |
--   | 8 bytes      | 2 bytes | n bytes |
--   </pre>
defaultArchiver :: Archiver


-- | AcidState container without a transaction log. Mostly used for
--   testing. Supports Atomicity, Consistency and Isolation, but not
--   Durability.
module Data.Acid.Memory

-- | Create an <a>AcidState</a> given an initial value. The state is kept
--   only in memory, so it is not durable.
openMemoryState :: IsAcidic st => st -> IO (AcidState st)


-- | AcidState container without a transaction log. Mostly used for
--   testing.
--   
--   This module consists of internal implementation details for
--   <a>Data.Acid.Memory</a>. You should not normally need to import it.
--   Call <a>openMemoryState</a> and thereafter use the API from
--   <a>Data.Acid</a> instead.
module Data.Acid.Memory.Pure
class IsAcidic st
acidEvents :: IsAcidic st => [Event st]

-- | Pure state value used internally. This is not the same as
--   <a>AcidState</a> from <a>Data.Acid</a>.
data AcidState st

-- | We distinguish between events that modify the state and those that do
--   not.
--   
--   UpdateEvents are executed in a MonadState context and have to be
--   serialized to disk before they are considered durable.
--   
--   QueryEvents are executed in a MonadReader context and obviously do not
--   have to be serialized to disk.
data Event st
[UpdateEvent] :: forall ev. UpdateEvent ev => (ev -> Update (EventState ev) (EventResult ev)) -> MethodSerialiser ev -> Event (MethodState ev)
[QueryEvent] :: forall ev. QueryEvent ev => (ev -> Query (EventState ev) (EventResult ev)) -> MethodSerialiser ev -> Event (MethodState ev)

-- | Events return the same thing as Methods. The exact type of
--   <a>EventResult</a> depends on the event.
type EventResult ev = MethodResult ev
type EventState ev = MethodState ev

-- | All UpdateEvents are also Methods.
class Method ev => UpdateEvent ev

-- | All QueryEvents are also Methods.
class Method ev => QueryEvent ev

-- | Context monad for Update events.
data Update st a

-- | Context monad for Query events.
data Query st a

-- | Create an AcidState given an initial value.
openAcidState :: IsAcidic st => st -> AcidState st

-- | Issue an Update event and wait for its result. Once this call returns,
--   you are guaranteed that the changes to the state are durable. Events
--   may be issued in parallel.
--   
--   It's a run-time error to issue events that aren't supported by the
--   AcidState.
update :: UpdateEvent event => AcidState (EventState event) -> event -> (AcidState (EventState event), EventResult event)

-- | Same as <a>update</a> but ignoring the event result.
update_ :: UpdateEvent event => AcidState (EventState event) -> event -> AcidState (EventState event)

-- | Issue a Query event and wait for its result.
query :: QueryEvent event => AcidState (EventState event) -> event -> EventResult event

-- | Run a query in the Update Monad.
liftQuery :: Query st a -> Update st a

-- | Execute the <a>Update</a> monad in a pure environment.
runUpdate :: Update s r -> s -> (r, s)

-- | Execute the <a>Query</a> monad in a pure environment.
runQuery :: Query s r -> s -> r


-- | This module provides the ability perform <a>update</a> and
--   <a>query</a> calls from a remote process.
--   
--   On the server-side you:
--   
--   <ol>
--   <li>open your <a>AcidState</a> normally</li>
--   <li>then use <a>acidServer</a> to share the state</li>
--   </ol>
--   
--   On the client-side you:
--   
--   <ol>
--   <li>use <a>openRemoteState</a> to connect to the remote state</li>
--   <li>use the returned <a>AcidState</a> like any other <a>AcidState</a>
--   handle</li>
--   </ol>
--   
--   <a>openRemoteState</a> and <a>acidServer</a> communicate over an
--   unencrypted socket. If you need an encrypted connection, see
--   <tt>acid-state-tls</tt>.
--   
--   On Unix®-like systems you can use <a>SockAddrUnix</a> to create a
--   socket file for local communication between the client and server.
--   Access can be controlled by setting the permissions of the parent
--   directory containing the socket file.
--   
--   It is also possible to perform some simple authentication using
--   <a>sharedSecretCheck</a> and <a>sharedSecretPerform</a>. Keep in mind
--   that secrets will be sent in plain-text if you do not use
--   <tt>acid-state-tls</tt>. If you are using a <a>SockAddrUnix</a>
--   additional authentication may not be required, so you can use
--   <a>skipAuthenticationCheck</a> and <a>skipAuthenticationPerform</a>.
--   
--   Working with a remote <a>AcidState</a> is nearly identical to working
--   with a local <a>AcidState</a> with a few important differences.
--   
--   The connection to the remote <a>AcidState</a> can be lost. The client
--   will automatically attempt to reconnect every second. Because
--   <a>query</a> events do not affect the state, an aborted <a>query</a>
--   will be retried automatically after the server is reconnected.
--   
--   If the connection was lost during an <a>update</a> event, the event
--   will not be retried. Instead <a>RemoteConnectionError</a> will be
--   raised. This is because it is impossible for the client to know if the
--   aborted update completed on the server-side or not.
--   
--   When using a local <a>AcidState</a>, an update event in one thread
--   does not block query events taking place in other threads. With a
--   remote connection, all queries and requests are channeled over a
--   single connection. As a result, updates and queries are performed in
--   the order they are executed and do block each other. In the rare case
--   where this is an issue, you could create one remote connection per
--   thread.
--   
--   When working with local state, a query or update which returns the
--   whole state is not usually a problem due to memory sharing. The
--   update/query event basically just needs to return a pointer to the
--   data already in memory. But, when working remotely, the entire result
--   will be serialized and sent to the remote client. Hence, it is good
--   practice to create queries and updates that will only return the
--   required data.
--   
--   This module is designed to be extenible. You can easily add your own
--   authentication methods by creating a suitable pair of functions and
--   passing them to <a>acidServer</a> and <a>openRemoteState</a>.
--   
--   It is also possible to create alternative communication layers using
--   <a>CommChannel</a>, <a>process</a>, and <a>processRemoteState</a>.
module Data.Acid.Remote

-- | Accept connections on <tt>port</tt> and handle requests using the
--   given <a>AcidState</a>. This call doesn't return.
--   
--   see also: <a>acidServerSockAddr</a>, <a>openRemoteState</a> and
--   <a>sharedSecretCheck</a>.
acidServer :: (CommChannel -> IO Bool) -> PortNumber -> AcidState st -> IO ()

-- | Accept connections on <tt>sockAddr</tt> and handle requests using the
--   given <a>AcidState</a>. This call doesn't return.
--   
--   see also: <a>acidServer</a>, <a>openRemoteState</a> and
--   <a>sharedSecretCheck</a>.
acidServerSockAddr :: (CommChannel -> IO Bool) -> SockAddr -> AcidState st -> IO ()

-- | Works the same way as <a>acidServer</a>, but uses pre-binded socket
--   <tt>listenSocket</tt>.
--   
--   Can be useful when fine-tuning of socket binding parameters is needed
--   (for example, listening on a particular network interface, IPv4/IPv6
--   options).
acidServer' :: (CommChannel -> IO Bool) -> Socket -> AcidState st -> IO ()

-- | Connect to an acid-state server which is sharing an <a>AcidState</a>.
openRemoteState :: IsAcidic st => (CommChannel -> IO ()) -> HostName -> PortNumber -> IO (AcidState st)

-- | Connect to an acid-state server which is sharing an <a>AcidState</a>.
openRemoteStateSockAddr :: IsAcidic st => (CommChannel -> IO ()) -> SockAddr -> IO (AcidState st)

-- | skip server-side authentication checking entirely.
skipAuthenticationCheck :: CommChannel -> IO Bool

-- | skip client-side authentication entirely.
skipAuthenticationPerform :: CommChannel -> IO ()

-- | check that the client knows a shared secret.
--   
--   The function takes a <a>Set</a> of shared secrets. If a client knows
--   any of them, it is considered to be trusted.
--   
--   The shared secret is any <tt>ByteString</tt> of your choice.
--   
--   If you give each client a different shared secret then you can revoke
--   access individually.
--   
--   see also: <a>sharedSecretPerform</a>
sharedSecretCheck :: Set ByteString -> CommChannel -> IO Bool

-- | attempt to authenticate with the server using a shared secret.
sharedSecretPerform :: ByteString -> CommChannel -> IO ()
data AcidRemoteException
RemoteConnectionError :: AcidRemoteException
AcidStateClosed :: AcidRemoteException
SerializeError :: String -> AcidRemoteException
AuthenticationError :: String -> AcidRemoteException

-- | <a>CommChannel</a> is a record containing the IO functions we need for
--   communication between the server and client.
--   
--   We abstract this out of the core processing function so that we can
--   easily add support for SSL/TLS and Unit testing.
data CommChannel
CommChannel :: (ByteString -> IO ()) -> (Int -> IO ByteString) -> IO () -> CommChannel
[ccPut] :: CommChannel -> ByteString -> IO ()
[ccGetSome] :: CommChannel -> Int -> IO ByteString
[ccClose] :: CommChannel -> IO ()

-- | Server inner-loop
--   
--   This function is generally only needed if you are adding a new
--   communication channel.
process :: CommChannel -> AcidState st -> IO ()

-- | Client inner-loop
--   
--   This function is generally only needed if you are adding a new
--   communication channel.
processRemoteState :: IsAcidic st => IO CommChannel -> IO (AcidState st)
instance GHC.Classes.Eq Data.Acid.Remote.AcidRemoteException
instance GHC.Internal.Exception.Type.Exception Data.Acid.Remote.AcidRemoteException
instance Data.Serialize.Serialize Data.Acid.Remote.Command
instance Data.Serialize.Serialize Data.Acid.Remote.Response
instance GHC.Internal.Show.Show Data.Acid.Remote.AcidRemoteException

module Data.Acid.TemplateHaskell

-- | Create the control structures required for acid states using Template
--   Haskell.
--   
--   This code:
--   
--   <pre>
--   myUpdate :: Argument -&gt; Update State Result
--   myUpdate arg = ...
--   
--   myQuery :: Argument -&gt; Query State Result
--   myQuery arg = ...
--   
--   $(makeAcidic ''State ['myUpdate, 'myQuery])
--   </pre>
--   
--   will make <tt>State</tt> an instance of <a>IsAcidic</a> and provide
--   the following events:
--   
--   <pre>
--   data MyUpdate = MyUpdate Argument
--   data MyQuery  = MyQuery Argument
--   </pre>
makeAcidic :: Name -> [Name] -> Q [Dec]

-- | Specifies how to customise the <a>IsAcidic</a> instance and event data
--   type serialisation instances for a particular serialisation layer.
data SerialiserSpec
SerialiserSpec :: Name -> Name -> (Name -> Type -> DecQ) -> SerialiserSpec

-- | Class for serialisable types, e.g. <tt>''Safecopy</tt>.
[serialisationClassName] :: SerialiserSpec -> Name

-- | Name of the <a>MethodSerialiser</a> to use in the list of events in
--   the <a>IsAcidic</a> instance.
[methodSerialiserName] :: SerialiserSpec -> Name

-- | Function to generate an instance of the class named by
--   <a>serialisationClassName</a>, given the event name and its type.
[makeEventSerialiser] :: SerialiserSpec -> Name -> Type -> DecQ

-- | Default implementation of <a>SerialiserSpec</a> that uses
--   <a>SafeCopy</a> for serialising events.
safeCopySerialiserSpec :: SerialiserSpec

-- | A variant on <a>makeAcidic</a> that makes it possible to explicitly
--   choose the serialisation implementation to be used for methods.
makeAcidicWithSerialiser :: SerialiserSpec -> Name -> [Name] -> Q [Dec]
makeAcidic' :: SerialiserSpec -> [Name] -> Name -> [TyVarBndrUnit] -> [Con] -> Q [Dec]

-- | Given an event name (e.g. <tt>'myUpdate</tt>), produce a data type
--   like
--   
--   <pre>
--   data MyUpdate = MyUpdate Argument
--   </pre>
--   
--   along with the <a>Method</a> class instance, <a>Event</a> class
--   instance and the instance of the appropriate serialisation class.
--   
--   However, if the event data type already exists, this will generate the
--   serialisation instance only. This makes it possible to call
--   <a>makeAcidicWithSerialiser</a> multiple times on the same events but
--   with different <a>SerialiserSpec</a>s, to support multiple
--   serialisation backends.
makeEvent :: SerialiserSpec -> Name -> Q [Dec]
getEventType :: Name -> Q Type
makeIsAcidic :: SerialiserSpec -> [Name] -> Name -> [TyVarBndr ()] -> p -> Q Dec

-- | This function analyses an event function and extracts any additional
--   class contexts which need to be added to the IsAcidic instance.
--   
--   For example, if we have:
--   
--   <pre>
--   data State a = ...
--   </pre>
--   
--   <pre>
--   setState :: (Ord a) =&gt; a -&gt; UpdateEvent (State a) ()
--   </pre>
--   
--   Then we need to generate an IsAcidic instance like:
--   
--   <pre>
--   instance (SafeCopy a, Typeable a, Ord a) =&gt; IsAcidic (State a)
--   </pre>
--   
--   Note that we can only add constraints for type variables which appear
--   in the State type. If we tried to do this:
--   
--   <pre>
--   setState :: (Ord a, Ord b) =&gt; a -&gt; b -&gt; UpdateEvent (State a) ()
--   </pre>
--   
--   We will get an ambigious type variable when trying to create the
--   <a>IsAcidic</a> instance, because there is no way to figure out what
--   type <tt>b</tt> should be.
--   
--   The tricky part of this code is that we need to unify the type
--   variables.
--   
--   Let's say the user writes their code using <tt>b</tt> instead of
--   <tt>a</tt>:
--   
--   <pre>
--   setState :: (Ord b) =&gt; b -&gt; UpdateEvent (State b) ()
--   </pre>
--   
--   In the <a>IsAcidic</a> instance, we are still going to use <tt>a</tt>.
--   So we need to rename the variables in the context to match.
--   
--   The contexts returned by this function will have the variables
--   renamed.
--   
--   Additionally, if the event uses MonadReader or MonadState it might
--   look like this:
--   
--   <pre>
--   setState :: (MonadState x m, IsFoo x) =&gt; m ()
--   </pre>
--   
--   In this case we have to rename <tt>x</tt> to the actual state we're
--   going to use. This is done by <a>renameState</a>.
eventCxts :: Type -> [TyVarBndrUnit] -> Name -> Type -> [Pred]

-- | See the end of comment for <a>eventCxts</a>.
renameState :: Type -> Type -> Cxt -> Cxt
makeEventHandler :: SerialiserSpec -> Name -> Type -> ExpQ
makeEventDataType :: Name -> Type -> DecQ
makeSafeCopyInstance :: Name -> Type -> DecQ
mkCxtFromTyVars :: Quote m => [Name] -> [TyVarBndr a] -> [Pred] -> m Cxt
makeMethodInstance :: Name -> Type -> DecQ
makeEventInstance :: Name -> Type -> DecQ
data TypeAnalysis
TypeAnalysis :: [TyVarBndrUnit] -> Cxt -> [Type] -> Type -> Type -> Bool -> TypeAnalysis
[tyvars] :: TypeAnalysis -> [TyVarBndrUnit]
[context] :: TypeAnalysis -> Cxt
[argumentTypes] :: TypeAnalysis -> [Type]
[stateType] :: TypeAnalysis -> Type
[resultType] :: TypeAnalysis -> Type
[isUpdate] :: TypeAnalysis -> Bool
analyseType :: Name -> Type -> TypeAnalysis

-- | find the type variables | e.g. State a b ==&gt; [a,b]
findTyVars :: Type -> [Name]

-- | extract the <a>Name</a> from a <a>TyVarBndr</a>
tyVarBndrName :: TyVarBndr a -> Name
allTyVarBndrNames :: [TyVarBndr a] -> [Name]

-- | Convert the <a>Name</a> of the event function into the name of the
--   corresponding data constructor.
toStructName :: Name -> Name
instance GHC.Classes.Eq Data.Acid.TemplateHaskell.TypeAnalysis
instance GHC.Internal.Show.Show Data.Acid.TemplateHaskell.TypeAnalysis


-- | A log is a stack of entries that supports efficient pushing of new
--   entries and fetching of old. It can be considered an extendible array
--   of entries.
module Data.Acid.Log
data FileLog object
FileLog :: LogKey object -> MVar FHandle -> TVar EntryId -> TVar ([ByteString], [IO ()]) -> [ThreadId] -> FileLog object
[logIdentifier] :: FileLog object -> LogKey object
[logCurrent] :: FileLog object -> MVar FHandle
[logNextEntryId] :: FileLog object -> TVar EntryId
[logQueue] :: FileLog object -> TVar ([ByteString], [IO ()])
[logThreads] :: FileLog object -> [ThreadId]
data LogKey object
LogKey :: FilePath -> String -> Serialiser object -> Archiver -> LogKey object
[logDirectory] :: LogKey object -> FilePath
[logPrefix] :: LogKey object -> String
[logSerialiser] :: LogKey object -> Serialiser object
[logArchiver] :: LogKey object -> Archiver
type EntryId = Int
openFileLog :: LogKey object -> IO (FileLog object)
closeFileLog :: FileLog object -> IO ()

-- | Schedule a new log entry. This call does not block. The given IO
--   action runs once the object is durable. The IO action blocks the
--   serialization of events so it should be swift.
pushEntry :: FileLog object -> object -> IO () -> IO ()

-- | The given IO action is executed once all previous entries are durable.
pushAction :: FileLog object -> IO () -> IO ()
ensureLeastEntryId :: FileLog object -> EntryId -> IO ()

-- | Read all durable entries younger than the given <a>EntryId</a>. Note
--   that entries written during or after this call won't be included in
--   the returned list.
readEntriesFrom :: FileLog object -> EntryId -> IO [object]

-- | Obliterate log entries younger than or equal to the <a>EntryId</a>.
--   Very unsafe, can't be undone
rollbackTo :: LogKey object -> EntryId -> IO ()

-- | Obliterate log entries as long as the filter function returns
--   <tt>True</tt>.
rollbackWhile :: LogKey object -> (object -> Bool) -> IO ()

-- | Finds the newest entry in the log. Doesn't work on open logs. Do not
--   use after the log has been opened.
--   
--   Implementation:
--   
--   <ul>
--   <li>Search the newest log files first.</li>
--   <li>Once a file containing at least one valid entry is found, return
--   the last entry in that file.</li>
--   </ul>
newestEntry :: LogKey object -> IO (Maybe object)
askCurrentEntryId :: FileLog object -> IO EntryId
cutFileLog :: FileLog object -> IO EntryId

-- | Move all log files that do not contain entries equal or higher than
--   the given entryId into an <tt>Archive/</tt> directory.
archiveFileLog :: FileLog object -> EntryId -> IO ()
findLogFiles :: LogKey object -> IO [(EntryId, FilePath)]


-- | AcidState container using a transaction log on disk. The term 'Event'
--   is loosely used for transactions with ACID guarantees. 'Method' is
--   loosely used for state operations without ACID guarantees (see
--   <a>Data.Acid.Core</a>).
module Data.Acid.Local

-- | Create an AcidState given an initial value.
--   
--   This will create or resume a log found in the "state/[typeOf state]/"
--   directory.
openLocalState :: (Typeable st, IsAcidic st, SafeCopy st) => st -> IO (AcidState st)

-- | Create an AcidState given a log directory and an initial value.
--   
--   This will create or resume a log found in <tt>directory</tt>. Running
--   two AcidState's from the same directory is an error but will not
--   result in dataloss.
openLocalStateFrom :: (IsAcidic st, SafeCopy st) => FilePath -> st -> IO (AcidState st)

-- | Create an AcidState given a log directory, an initial value and a
--   serialisation layer.
--   
--   This will create or resume a log found in <tt>directory</tt>. Running
--   two AcidState's from the same directory is an error but will not
--   result in dataloss.
openLocalStateWithSerialiser :: IsAcidic st => FilePath -> st -> SerialisationLayer st -> IO (AcidState st)

-- | Create an AcidState given an initial value.
--   
--   This will create or resume a log found in the "state/[typeOf state]/"
--   directory. The most recent checkpoint will be loaded immediately but
--   the AcidState will not be opened until the returned function is
--   executed.
prepareLocalState :: (Typeable st, IsAcidic st, SafeCopy st) => st -> IO (IO (AcidState st))

-- | Create an AcidState given a log directory and an initial value.
--   
--   This will create or resume a log found in <tt>directory</tt>. The most
--   recent checkpoint will be loaded immediately but the AcidState will
--   not be opened until the returned function is executed.
prepareLocalStateFrom :: (IsAcidic st, SafeCopy st) => FilePath -> st -> IO (IO (AcidState st))

-- | Create an AcidState given a log directory, an initial value and a
--   serialisation layer.
--   
--   This will create or resume a log found in <tt>directory</tt>. The most
--   recent checkpoint will be loaded immediately but the AcidState will
--   not be opened until the returned function is executed.
prepareLocalStateWithSerialiser :: IsAcidic st => FilePath -> st -> SerialisationLayer st -> IO (IO (AcidState st))

-- | Directory to load the state from unless otherwise specified, namely
--   "state/[typeOf state]/".
defaultStateDirectory :: Typeable st => st -> FilePath

-- | Same as scheduleLocalUpdate but does not immediately change the
--   localCopy and return the result mvar - returns an IO action to do this
--   instead. Take care to run actions of multiple Updates in the correct
--   order as otherwise Queries will operate on outdated state.
scheduleLocalUpdate' :: UpdateEvent event => LocalState (EventState event) -> event -> MVar (EventResult event) -> IO (IO ())

-- | Same as scheduleLocalColdUpdate but does not immediately change the
--   localCopy and return the result mvar - returns an IO action to do this
--   instead. Take care to run actions of multiple Updates in the correct
--   order as otherwise Queries will operate on outdated state.
scheduleLocalColdUpdate' :: LocalState st -> Tagged ByteString -> MVar ByteString -> IO (IO ())

-- | Save a snapshot to disk and close the AcidState as a single atomic
--   action. This is useful when you want to make sure that no events are
--   saved to disk after a checkpoint.
createCheckpointAndClose :: (IsAcidic st, Typeable st) => AcidState st -> IO ()

-- | State container offering full ACID (Atomicity, Consistency, Isolation
--   and Durability) guarantees.
--   
--   <ul>
--   <li><i><tt>Atomicity</tt></i> State changes are all-or-nothing. This
--   is what you'd expect of any state variable in Haskell and AcidState
--   doesn't change that.</li>
--   <li><i><tt>Consistency</tt></i> No event or set of events will break
--   your data invariants.</li>
--   <li><i><tt>Isolation</tt></i> Transactions cannot interfere with each
--   other even when issued in parallel.</li>
--   <li><i><tt>Durability</tt></i> Successful transaction are guaranteed
--   to survive system failure (both hardware and software).</li>
--   </ul>
data LocalState st
LocalState :: Core st -> IORef st -> FileLog (Tagged ByteString) -> FileLog (Checkpoint st) -> FileLock -> LocalState st
[localCore] :: LocalState st -> Core st
[localCopy] :: LocalState st -> IORef st
[localEvents] :: LocalState st -> FileLog (Tagged ByteString)
[localCheckpoints] :: LocalState st -> FileLog (Checkpoint st)
[localLock] :: LocalState st -> FileLock
data Checkpoint s
Checkpoint :: EntryId -> s -> Checkpoint s
data SerialisationLayer st
SerialisationLayer :: Serialiser (Checkpoint st) -> Serialiser (Tagged ByteString) -> Archiver -> SerialisationLayer st

-- | Serialisation strategy for checkpoints.
--   
--   Use <a>safeCopySerialiser</a> for the backwards-compatible
--   implementation using <a>Data.SafeCopy</a>.
[checkpointSerialiser] :: SerialisationLayer st -> Serialiser (Checkpoint st)

-- | Serialisation strategy for events.
--   
--   Use <a>safeCopySerialiser</a> for the backwards-compatible
--   implementation using <a>Data.SafeCopy</a>.
[eventSerialiser] :: SerialisationLayer st -> Serialiser (Tagged ByteString)

-- | Serialisation strategy for archive log files.
--   
--   Use <a>defaultArchiver</a> for the backwards-compatible implementation
--   using <a>Data.Serialize</a>.
[archiver] :: SerialisationLayer st -> Archiver

-- | Standard (and historically the only) serialisation layer, using
--   <a>safeCopySerialiser</a> and <a>defaultArchiver</a>.
defaultSerialisationLayer :: SafeCopy st => SerialisationLayer st
mkEventsLogKey :: FilePath -> SerialisationLayer object -> LogKey (Tagged ByteString)
mkCheckpointsLogKey :: FilePath -> SerialisationLayer object -> LogKey (Checkpoint object)
instance GHC.Internal.Exception.Type.Exception Data.Acid.Local.StateIsLocked
instance Data.SafeCopy.SafeCopy.SafeCopy s => Data.SafeCopy.SafeCopy.SafeCopy (Data.Acid.Local.Checkpoint s)
instance GHC.Internal.Show.Show Data.Acid.Local.StateIsLocked

module Data.Acid.Repair

-- | <tt><a>repairFile</a> path</tt> will truncate the entries in
--   <tt>file</tt> until there are only valid entries (if a corrupted entry
--   is found, then the rest of the file is truncated).
--   
--   The old file will be copied to <tt>path.bak</tt> (or
--   <tt>path.bak.1</tt>, etc… if the file already exists).
--   
--   <a>repairFile</a> tries very hard to avoid leaving files in an
--   inconsistent state: the truncated file is written in a temporary file,
--   which is then moved into place, similarly copies are performed with
--   moves instead. Still this is not fully atomic: there are two
--   consecutive moves, so <a>repairFile</a> may, in case of crash, yield a
--   state where the <tt>path.bak</tt> file is there but no <tt>path</tt>
--   is there anymore, this would require manual intervention.
repairFile :: FilePath -> IO ()

-- | Repairs the WAL files with the following strategy:
--   
--   <ul>
--   <li>Let <tt>f</tt> be the oldest corrupted file.</li>
--   <li>All files older than <tt>f</tt> is left untouched</li>
--   <li><tt>f</tt> is repaired with <a>repairFile</a></li>
--   <li>Old files younger than <tt>f</tt> is dropped (and saved to
--   `path.bak`, or `path.bak.1`, etc…)</li>
--   </ul>
--   
--   In other words, all the log entries after the first corrupted entry is
--   dropped. The reasoning is that newer entries are likely not to make
--   sense after some entries have been removed from the log. This strategy
--   guarantees a consistent state, albeit a potentially old one.
repairEvents :: FilePath -> IO ()

-- | Repairs the checkpoints file using the following strategy:
--   
--   <ul>
--   <li>Every checkpoints file is repaired with <a>repairFile</a></li>
--   </ul>
--   
--   Checkpoints are mostly independent. Contrary to <a>repairEvents</a>,
--   dropping a checkpoint doesn't affect the consistency of later
--   checkpoints.
repairCheckpoints :: FilePath -> IO ()


-- | AcidState container using a transaction log on disk.
--   
--   To see how it all fits together, have a look at these example
--   <a>https://github.com/acid-state/acid-state/tree/master/examples</a>.
module Data.Acid

-- | State container offering full ACID (Atomicity, Consistency, Isolation
--   and Durability) guarantees.
--   
--   <ul>
--   <li><i><tt>Atomicity</tt></i> State changes are all-or-nothing. This
--   is what you'd expect of any state variable in Haskell and AcidState
--   doesn't change that.</li>
--   <li><i><tt>Consistency</tt></i> No event or set of events will break
--   your data invariants.</li>
--   <li><i><tt>Isolation</tt></i> Transactions cannot interfere with each
--   other even when issued in parallel.</li>
--   <li><i><tt>Durability</tt></i> Successful transaction are guaranteed
--   to survive unexpected system shutdowns (both those caused by hardware
--   and software).</li>
--   </ul>
data AcidState st

-- | Create an AcidState given an initial value.
--   
--   This will create or resume a log found in the "state/[typeOf state]/"
--   directory.
openLocalState :: (Typeable st, IsAcidic st, SafeCopy st) => st -> IO (AcidState st)

-- | Create an AcidState given a log directory and an initial value.
--   
--   This will create or resume a log found in <tt>directory</tt>. Running
--   two AcidState's from the same directory is an error but will not
--   result in dataloss.
openLocalStateFrom :: (IsAcidic st, SafeCopy st) => FilePath -> st -> IO (AcidState st)
closeAcidState :: AcidState st -> IO ()
createCheckpoint :: AcidState st -> IO ()
createArchive :: AcidState st -> IO ()

-- | Issue an Update event and wait for its result. Once this call returns,
--   you are guaranteed that the changes to the state are durable. Events
--   may be issued in parallel.
--   
--   It's a run-time error to issue events that aren't supported by the
--   AcidState.
update :: UpdateEvent event => AcidState (EventState event) -> event -> IO (EventResult event)

-- | Issue a Query event and wait for its result. Events may be issued in
--   parallel.
query :: QueryEvent event => AcidState (EventState event) -> event -> IO (EventResult event)

-- | Events return the same thing as Methods. The exact type of
--   <a>EventResult</a> depends on the event.
type EventResult ev = MethodResult ev
type EventState ev = MethodState ev

-- | All UpdateEvents are also Methods.
class Method ev => UpdateEvent ev

-- | All QueryEvents are also Methods.
class Method ev => QueryEvent ev

-- | Context monad for Update events.
data Update st a

-- | Context monad for Query events.
data Query st a
class IsAcidic st

-- | Create the control structures required for acid states using Template
--   Haskell.
--   
--   This code:
--   
--   <pre>
--   myUpdate :: Argument -&gt; Update State Result
--   myUpdate arg = ...
--   
--   myQuery :: Argument -&gt; Query State Result
--   myQuery arg = ...
--   
--   $(makeAcidic ''State ['myUpdate, 'myQuery])
--   </pre>
--   
--   will make <tt>State</tt> an instance of <a>IsAcidic</a> and provide
--   the following events:
--   
--   <pre>
--   data MyUpdate = MyUpdate Argument
--   data MyQuery  = MyQuery Argument
--   </pre>
makeAcidic :: Name -> [Name] -> Q [Dec]

-- | Run a query in the Update Monad.
liftQuery :: Query st a -> Update st a
