Data.StableTree.Persist

Logic for dealing with the actual persistence of Stable Trees. The key exports here are Error, load, and store. A user needs to make an appropriate Error type to report storage errors, and then the load and store functions can just do their thing. If necessary, a user can also implement Serialize for custom data types.

Documentation

class Error e where

Things go wrong with end-user storage, but things can also go wrong with reconstructing tree values. Implement stableTreeError to allow load and store to report their own errors.

Methods

stableTreeError :: Text -> e

data Fragment k v

A Fragment is a user-visible part of a tree, i.e. a single node in the tree that can actually be manipulated by a user. This is useful when doing the work of persisting trees. See toFragments and fromFragments for functions to convert between Fragments and Trees. see store and load for functions related to storing and retrieving Fragments.

Constructors

FragmentBranch

Fields

fragmentObjectID :: ObjectID

fragmentDepth :: Depth

fragmentChildren :: Map k (ValueCount, ObjectID)

FragmentBottom

Fields

fragmentObjectID :: ObjectID

fragmentMap :: Map k v

Instances

(Eq k, Eq v) => Eq (Fragment k v)

(Ord k, Ord v) => Ord (Fragment k v)

(Show k, Show v) => Show (Fragment k v)

(Ord k, Serialize k, Serialize v) => Serialize (Fragment k v)

store :: (Monad m, Error e, Ord k, Serialize k, StableKey k, Serialize v) => (a -> ObjectID -> Fragment k v -> m (Either e a)) -> a -> StableTree k v -> m (Either e a)

Record the tree into storage. This works like a fold, where the function takes an accumulating state and each tree fragment to store, while returning either an error message (which will abort the loop immediately) or the next state for the accumulator.

Any fragment referring to other fragments (FragmentBranch fragments) will be given to the fold only after all their children have been given to the fold. Exact ordering beyond that is not guaranteed, but the current behaviour is post-order depth-first traversal.

store' :: (Monad m, Error e, Ord k, Serialize k, StableKey k, Serialize v) => (ObjectID -> Fragment k v -> m (Maybe e)) -> StableTree k v -> m (Either e ObjectID)

Alternate store function that acts more like a map than a fold. See store for details.

load :: (Monad m, Error e, Ord k, Serialize k, StableKey k, Serialize v) => (a -> ObjectID -> m (Either e (a, Fragment k v))) -> a -> ObjectID -> m (Either e (a, StableTree k v))

Reverse of store. As with store, this acts like a fold, but converts an ObjectID into a tree, rather than storing a tree. This will always build the tree from the top down.

load' :: (Monad m, Error e, Ord k, Serialize k, StableKey k, Serialize v) => (ObjectID -> m (Either e (Fragment k v))) -> ObjectID -> m (Either e (StableTree k v))

Version of load that acts like a map rather than a fold.