Database.VCache

Documentation

module Database.VCache.VRef

module Database.VCache.PVar

module Database.VCache.VTx

data VCache

VCache supports a filesystem-backed address space plus a set of persistent, named root variables that can be loaded from one run of the application to another. VCache supports a simple filesystem like model to resist namespace collisions between named roots.

openVCache   :: Int -> FilePath -> IO VCache
vcacheSubdir :: ByteString -> VCache -> VCache
loadRootPVar :: (VCacheable a) => VCache -> ByteString -> a -> PVar a

The normal use of VCache is to open VCache in the main function, use vcacheSubdir for each major framework, plugin, or independent component that might need persistent storage, then load at most a few root PVars per component. Most domain modeling should be at the data layer, i.e. the type held by the PVar.

See VSpace, VRef, and PVar for more information.

Instances

Eq VCache

openVCache :: Int -> FilePath -> IO VCache

Open a VCache with a given database file.

In most cases, a Haskell process should open VCache in the Main module then pass it as an argument to the different libraries, frameworks, plugins, and other software components that require persistent storage. Use vcacheSubdir to progect against namespace collisions.

When opening VCache, developers decide the maximum size and the file name. For example:

vc <- openVCache 100 "db"

This would open a VCache whose file-size limit is 100 megabytes, with the name "db", plus an additional "db-lock" lockfile. An exception will be raised if these files cannot be created, locked, or opened. The size limit is passed to LMDB and is separate from setVRefsCacheSize.

Once opened, VCache typically remains open until process halt. If errors are detected, e.g. due to writing an undefined value to a PVar or running out of space, VCache will attempt to halt the process.

data VSpace

VSpace represents the virtual address space used by VCache. Except for loadRootPVar, most operations use VSpace rather than the VCache. VSpace is accessed by vcache_space, vref_space, or pvar_space.

Addresses from this space are allocated incrementally, odds to PVars and evens to VRefs, independent of object size. The space is elastic: it isn't a problem to change the size of PVars (even drastically) from one update to another.

In theory, VSpace could run out of 64-bit addresses. In practice, this isn't a real concern - a quarter million years at a sustained million allocations per second.

Instances

Eq VSpace

vcache_space :: VCache -> VSpace

virtual address space for VCache

module Database.VCache.Path

module Database.VCache.Stats

module Database.VCache.Sync

module Database.VCache.VCacheable