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

Copyright | PublicDomain
Maintainer | lemmih@gmail.com
Portability | non-portable (uses GHC extensions)
Safe Haskell | None
Language | Haskell2010

Data.Acid.Local

Description

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 Data.Acid.Core).

Synopsis

- openLocalState :: (Typeable st, IsAcidic st, SafeCopy st) => st -> IO (AcidState st)
- openLocalStateFrom :: (IsAcidic st, SafeCopy st) => FilePath -> st -> IO (AcidState st)
- openLocalStateWithSerialiser :: IsAcidic st => FilePath -> st -> SerialisationLayer st -> IO (AcidState st)
- prepareLocalState :: (Typeable st, IsAcidic st, SafeCopy st) => st -> IO (IO (AcidState st))
- prepareLocalStateFrom :: (IsAcidic st, SafeCopy st) => FilePath -> st -> IO (IO (AcidState st))
- prepareLocalStateWithSerialiser :: IsAcidic st => FilePath -> st -> SerialisationLayer st -> IO (IO (AcidState st))
- defaultStateDirectory :: Typeable st => st -> FilePath
- scheduleLocalUpdate' :: UpdateEvent event => LocalState (EventState event) -> event -> MVar (EventResult event) -> IO (IO ())
- scheduleLocalColdUpdate' :: LocalState st -> Tagged ByteString -> MVar ByteString -> IO (IO ())
- createCheckpointAndClose :: (IsAcidic st, Typeable st) => AcidState st -> IO ()
- data LocalState st = LocalState {
  - localCore :: Core st
  - localCopy :: IORef st
  - localEvents :: FileLog (Tagged ByteString)
  - localCheckpoints :: FileLog (Checkpoint st)
  - localLock :: FileLock
  }
- data Checkpoint s = Checkpoint EntryId s
- data SerialisationLayer st = SerialisationLayer {
  - checkpointSerialiser :: Serialiser (Checkpoint st)
  - eventSerialiser :: Serialiser (Tagged ByteString)
  - archiver :: Archiver
  }
- defaultSerialisationLayer :: SafeCopy st => SerialisationLayer st
- mkEventsLogKey :: FilePath -> SerialisationLayer object -> LogKey (Tagged ByteString)
- mkCheckpointsLogKey :: FilePath -> SerialisationLayer object -> LogKey (Checkpoint object)

# Documentation

openLocalState Source #

Arguments

:: (Typeable st, IsAcidic st, SafeCopy 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, SafeCopy 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.

openLocalStateWithSerialiser 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.
-> SerialisationLayer st | Serialisation layer to use for checkpoints, events and archives.
-> 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 `directory`. Running two AcidState's from the same directory is an error but will not result in dataloss.

prepareLocalState Source #

Arguments

:: (Typeable st, IsAcidic st, SafeCopy st) |
=> st | Initial state value. This value is only used if no checkpoint is found.
-> IO (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.

prepareLocalStateFrom Source #

Arguments

:: (IsAcidic st, SafeCopy st) |
=> FilePath | Location of the checkpoint and transaction files.
-> st | Initial state value. This value is only used if no checkpoint is found.
-> IO (IO (AcidState st)) |

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

This will create or resume a log found in `directory`. The most recent checkpoint will be loaded immediately but the AcidState will not be opened until the returned function is executed.

prepareLocalStateWithSerialiser 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.
-> SerialisationLayer st | Serialisation layer to use for checkpoints, events and archives.
-> 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 `directory`. The most recent checkpoint will be loaded immediately but the AcidState will not be opened until the returned function is executed.

defaultStateDirectory :: Typeable st => st -> FilePath Source #

Directory to load the state from unless otherwise specified, namely "state/[typeOf state]/".

scheduleLocalUpdate' :: UpdateEvent event => LocalState (EventState event) -> event -> MVar (EventResult event) -> IO (IO ()) Source #

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.

scheduleLocalColdUpdate' :: LocalState st -> Tagged ByteString -> MVar ByteString -> IO (IO ()) Source #

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.

createCheckpointAndClose :: (IsAcidic st, Typeable st) => AcidState st -> IO () Source #

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.

data LocalState 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 system failure (both hardware and software).

Constructors

LocalState |

Fields

- localCore :: Core st
- localCopy :: IORef st
- localEvents :: FileLog (Tagged ByteString)
- localCheckpoints :: FileLog (Checkpoint st)
- localLock :: FileLock

data Checkpoint s Source #

Constructors

Checkpoint EntryId s |

#### Instances

Instances details

SafeCopy s => SafeCopy (Checkpoint s) Source #

Previous versions of `acid-state` had

    data Checkpoint = Checkpoint EntryId ByteString

where the `ByteString` is the `safecopy`-serialization of the original checkpoint data. Thus we give a `SafeCopy` instance that is backwards-compatible with this by making nested calls to `safePut` and `safeGet`.

Note that if the inner data cannot be deserialised, `getCopy` will not report an error immediately but will return a `Checkpoint` whose payload is an error thunk. This means consumers can skip deserialising intermediate checkpoint data when they care only about the last checkpoint in a file. However, they must be sure to force the returned data promptly.

Instance details Defined in Data.Acid.Local Methods version :: Version (Checkpoint s) Source # kind :: Kind (Checkpoint s) Source # getCopy :: Contained (Get (Checkpoint s)) Source # putCopy :: Checkpoint s -> Contained Put Source # internalConsistency :: Consistency (Checkpoint s) Source # objectProfile :: Profile (Checkpoint s) Source # errorTypeName :: Proxy (Checkpoint s) -> String Source #

data SerialisationLayer st Source #

Constructors

SerialisationLayer |

Fields

- checkpointSerialiser :: Serialiser (Checkpoint st)

  Serialisation strategy for checkpoints.

  Use `safeCopySerialiser` for the backwards-compatible implementation using Data.SafeCopy.

- eventSerialiser :: Serialiser (Tagged ByteString)

  Serialisation strategy for events.

  Use `safeCopySerialiser` for the backwards-compatible implementation using Data.SafeCopy.

- archiver :: Archiver

  Serialisation strategy for archive log files.

  Use `defaultArchiver` for the backwards-compatible implementation using Data.Serialize.

defaultSerialisationLayer :: SafeCopy st => SerialisationLayer st Source #

Standard (and historically the only) serialisation layer, using `safeCopySerialiser` and `defaultArchiver`.

mkEventsLogKey :: FilePath -> SerialisationLayer object -> LogKey (Tagged ByteString) Source #

mkCheckpointsLogKey :: FilePath -> SerialisationLayer object -> LogKey (Checkpoint object) Source #