acid-state-0.15.0: Add ACID guarantees to any serializable Haskell data structure.

CopyrightPublicDomain
Maintainerlemmih@gmail.com
Portabilitynon-portable (uses GHC extensions)
Safe HaskellNone
LanguageHaskell2010

Data.Acid

Description

AcidState container using a transaction log on disk.

To see how it all fits together, have a look at these example https://github.com/acid-state/acid-state/tree/master/examples.

Synopsis

Documentation

data AcidState st Source #

State container offering full ACID (Atomicity, Consistency, Isolation and Durability) guarantees.

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

openLocalState Source #

Arguments

:: (Typeable st, IsAcidic st) 
=> st

Initial state value. This value is only used if no checkpoint is found.

-> IO (AcidState st) 

Create an AcidState given an initial value.

This will create or resume a log found in the "state/[typeOf state]/" directory.

openLocalStateFrom Source #

Arguments

:: IsAcidic st 
=> FilePath

Location of the checkpoint and transaction files.

-> st

Initial state value. This value is only used if no checkpoint is found.

-> IO (AcidState st) 

Create an AcidState given a log directory and an initial value.

This will create or resume a log found in directory. Running two AcidState's from the same directory is an error but will not result in dataloss.

closeAcidState :: AcidState st -> IO () Source #

Close an AcidState and associated resources. Any subsequent usage of the AcidState will throw an exception.

createCheckpoint :: AcidState st -> IO () Source #

Take a snapshot of the state and save it to disk. Creating checkpoints makes it faster to resume AcidStates and you're free to create them as often or seldom as fits your needs. Transactions can run concurrently with this call.

This call will not return until the operation has succeeded.

createArchive :: AcidState st -> IO () Source #

Move all log files that are no longer necessary for state restoration into the Archive folder in the state directory. This folder can then be backed up or thrown out as you see fit. Reverting to a state before the last checkpoint will not be possible if the Archive folder has been thrown out.

This method is idempotent and does not block the normal operation of the AcidState.

update :: UpdateEvent event => AcidState (EventState event) -> event -> IO (EventResult event) Source #

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.

query :: QueryEvent event => AcidState (EventState event) -> event -> IO (EventResult event) Source #

Issue a Query event and wait for its result. Events may be issued in parallel.

type EventResult ev = MethodResult ev Source #

Events return the same thing as Methods. The exact type of EventResult depends on the event.

class Method ev => UpdateEvent ev Source #

All UpdateEvents are also Methods.

class Method ev => QueryEvent ev Source #

All QueryEvents are also Methods.

data Update st a Source #

Context monad for Update events.

Instances
MonadState st (Update st) Source # 
Instance details

Defined in Data.Acid.Common

Methods

get :: Update st st #

put :: st -> Update st () #

state :: (st -> (a, st)) -> Update st a #

Monad (Update st) Source # 
Instance details

Defined in Data.Acid.Common

Methods

(>>=) :: Update st a -> (a -> Update st b) -> Update st b #

(>>) :: Update st a -> Update st b -> Update st b #

return :: a -> Update st a #

fail :: String -> Update st a #

Functor (Update st) Source # 
Instance details

Defined in Data.Acid.Common

Methods

fmap :: (a -> b) -> Update st a -> Update st b #

(<$) :: a -> Update st b -> Update st a #

Applicative (Update st) Source # 
Instance details

Defined in Data.Acid.Common

Methods

pure :: a -> Update st a #

(<*>) :: Update st (a -> b) -> Update st a -> Update st b #

liftA2 :: (a -> b -> c) -> Update st a -> Update st b -> Update st c #

(*>) :: Update st a -> Update st b -> Update st b #

(<*) :: Update st a -> Update st b -> Update st a #

data Query st a Source #

Context monad for Query events.

Instances
MonadReader st (Query st) Source # 
Instance details

Defined in Data.Acid.Common

Methods

ask :: Query st st #

local :: (st -> st) -> Query st a -> Query st a #

reader :: (st -> a) -> Query st a #

Monad (Query st) Source # 
Instance details

Defined in Data.Acid.Common

Methods

(>>=) :: Query st a -> (a -> Query st b) -> Query st b #

(>>) :: Query st a -> Query st b -> Query st b #

return :: a -> Query st a #

fail :: String -> Query st a #

Functor (Query st) Source # 
Instance details

Defined in Data.Acid.Common

Methods

fmap :: (a -> b) -> Query st a -> Query st b #

(<$) :: a -> Query st b -> Query st a #

Applicative (Query st) Source # 
Instance details

Defined in Data.Acid.Common

Methods

pure :: a -> Query st a #

(<*>) :: Query st (a -> b) -> Query st a -> Query st b #

liftA2 :: (a -> b -> c) -> Query st a -> Query st b -> Query st c #

(*>) :: Query st a -> Query st b -> Query st b #

(<*) :: Query st a -> Query st b -> Query st a #

class SafeCopy st => IsAcidic st Source #

Minimal complete definition

acidEvents

makeAcidic :: Name -> [Name] -> Q [Dec] Source #

Create the control structures required for acid states using Template Haskell.

This code:

myUpdate :: Argument -> Update State Result
myUpdate arg = ...

myQuery :: Argument -> Query State Result
myQuery arg = ...

$(makeAcidic ''State ['myUpdate, 'myQuery])

will make State an instance of IsAcidic and provide the following events:

data MyUpdate = MyUpdate Argument
data MyQuery  = MyQuery Argument

liftQuery :: Query st a -> Update st a Source #

Run a query in the Update Monad.