Data.HMemDb

This library allows one to create mutable (but thread-safe) lists of values and access them quickly with certain automatically updated indices (foreign keys).

Documentation

type MS = MaybeT STM

type GS = Get :. STM

type SP = (STM :. PutM) ()

Tables

data Table a

This type represent tables. Each table is the set of values. Individual values can be accessed with TableVars or ForeignKeys. Tables are never created manually, they should be generated by createTable or loaded by getTable. Both functions require the structure of the table to be described as the FullSpec.

foldTable_ :: (a -> MS b) -> Table a -> STM ()

This function traverses through all values in the table, applying the same action to all of them. Errors are silently ignored.

type TableVar = TableVarS Id

This type represents references to individual values in the table. It is returned by insert and select functions.

data TableVarS s a

This is a more generic type, which represents a set of values in the same table.

Instances

IsId s => Eq (TableVarS s a)

TableVars from different Tables may coincidentally appear as equal.

IsId s => Ord (TableVarS s a)

class IsId s

This class is here for technical reasons, it should only have one instance whatsoever.

Instances

IsId Id

tableVarTarget :: TableVarS s a -> Table a

This function returns the Table that the TableVar is from.

forTV :: (Foldable s, Applicative f) => (TableVar a -> f b) -> TableVarS s a -> f ()

This function iterates through all elements of the set.

deleteTV :: TableVar a -> MS a

This function removes the value from whatever table it's in. It returnes the original value, provided that it wasn't removed before or invalidated by removing some other value this one references with ForeignKey.

modifyTV :: a -> TableVar a -> MS a

This function overrides the value with another one. All indices referencing the original value would be referencing the new one. It fails if the original value was removed before or became invalid.

readTV :: TableVar a -> MS a

This function reads the value from the table. It fails if the value was removed before or became invalid.

selectAll :: Table a -> STM (TableVarS Set a)

This function gives the set of all values in the table.

data ForeignKey s i a

This is a type of foreign keys. Each foreign key points to one table. It is used to find the values in this table using select. Foreign keys are created at the same time Tables are. They can't be added afterwards.

keyTarget :: ForeignKey s i a -> Table a

This function returns the table that the key points to.

Specs

data FullSpec a u

This is the full specification, of both table and set of keys, which should be fed to createTable and getTable functions.

Constructors

FullSpec

Fields

tabSpec :: TableSpec a

keySpec :: u a KeySpec

Table specs

newtype TableSpec a

This type represents the table structure. It can be generated using the Applicative interface of the ColSpec like this:

 data MyData = {myField1 :: Integer, myField2 :: String}
 tabSpec = TableSpec (MyData <$> val myField1 <*> val myField2)

Constructors

TableSpec (ColSpec a a)

data ColSpec input output

This is the internal of the TableSpec type.

Instances

Functor (ColSpec input)

Applicative (ColSpec input)

val :: Binary col => (input -> col) -> ColSpec input col

This function specifies one column in the table. It instructs the library to store one part of the value.

key :: Ord i => ForeignKey Id i col -> (input -> i) -> ColSpec input col

This function specifies one column in the table. Unlike val, it doesn't store some part of the value; instead it stores the reference to some other table.

Key specs

data KeySpec s i a

This is the specification of one ForeignKey. It could be unique or non-unique.

Instances

(Ord i, RefContainer s) => IsKeySpec (KeySpec s i)

unique :: (a -> i) -> KeySpec Id i a

This function specifies a unique key.

nonunique :: (a -> i) -> KeySpec Set i a

This function specifies a non-unique key.

Creating tables

createTable :: CreateTable u => FullSpec a u -> STM (Table a, u a ForeignKey)

This function creates an empty table, given the table structure (TableSpec) and the set of keys (KeySpec). It returns the table itself, accompanied with the same set of foreign keys, allowing one to search through the table quickly, or to make a new TableSpec.

data Keys a h

This type represents an empty set of KeySpecs or ForeignKeys.

Constructors

Keys

Instances

CreateTable Keys

class Foldable s => RefContainer s

This class is a closed one; the user is not supposed to create new instances. It allows treating unique and non-unique keys in the same way.

Instances

RefContainer Id

RefContainer Set

class IsKeySpec ks

This class is here for technical reasons; it has just one instance.

Instances

(Ord i, RefContainer s) => IsKeySpec (KeySpec s i)

data (u :+: ks) a h where

This type operator adds one more KeySpec to the set, or allows to get a ForeignKey back with pattern-matching. Use it like this:

 do (table, ... :+: foreignKey)
      <- createTable $ FullSpec {..., keySpec = ... :+: unique myKey}

Constructors

:+: :: u a h -> h s i a -> (u :+: KeySpec s i) a h

Instances

(CreateTable u, IsKeySpec ks) => CreateTable (:+: u ks)

class CreateTable u

This is a class of sets of KeySpecs and ForeignKeys

Instances

CreateTable Keys

(CreateTable u, IsKeySpec ks) => CreateTable (:+: u ks)

Basic operations

insert :: a -> Table a -> MS (TableVar a)

This function inserts a new value into the table and gives a TableVar back. Failure indicates that one of the unique indices for this value coincides with the same index of another value already present in the table. It won't happen for non-unique indices.

select :: Ord i => ForeignKey s i a -> i -> MS (TableVarS s a)

This function searches for some particular index in the table. It fails if there is no value with that index. Empty set of values is never returned. For non-unique indices it returns the set of TableVars.

delete :: (Foldable s, Ord i) => ForeignKey s i a -> i -> STM ()

This function deletes the value from the table. It won't be accessible anymore. It never fails; nonexistent values are silently skipped.

update :: Ord i => ForeignKey Id i a -> i -> a -> MS a

This function overrides the existing value in the table with the new one. All foreign keys pointing to the original value become pointing to the new value. It returns the original value, which is no longer in the table. Failure means that there was no such value.

Serialization

getTable :: CreateTable u => FullSpec a u -> GS (Table a, u a ForeignKey)

This function reads the table from the ByteString. As the table structure is NOT stored, one should provide the same one that was used to create this table

putTable :: Table a -> SP

This function saves the table to the ByteString. Note that it doesn't really matter if the type of values in the table are serializable.

NB: if any index used to access the values in this table depended on any foreign keys, and targets of these keys have changed, the index could be different after storing and restoring the table.