Database.VCache.VGet

Documentation

data VGet a

VGet is a parser combinator monad for VCache. Unlike pure binary parsers, VGet supports reads from a stack of VRefs and PVars to directly model structured data.

Instances

Alternative VGet

Monad VGet

Functor VGet

MonadPlus VGet

Applicative VGet

Prim Readers

getVRef :: VCacheable a => VGet (VRef a)

Load a VRef, just the reference rather than the content. User must know the type of the value, since getVRef is essentially a typecast. VRef content is not read until deref.

All instances of a VRef with the same type and address will share the same cache.

getPVar :: VCacheable a => VGet (PVar a)

Load a PVar, just the variable. Content is loaded lazily on first read, then kept in memory until the PVar is GC'd. Unlike other Haskell variables, PVars can be serialized to the VCache address space. All PVars for a specific address are collapsed, using the same TVar.

Developers must know the type of the PVar, since getPVar will cast to any cacheable type. A runtime error is raised only if you attempt to load the same PVar address with two different types.

getVSpace :: VGet VSpace

Obtain the VSpace associated with content being read. Does not consume any data.

getWord8 :: VGet Word8

Read one byte of data, or fail if not enough data.

getWord16le :: VGet Word16

Read words of size 16, 32, or 64 in little-endian or big-endian.

getWord16be :: VGet Word16

Read words of size 16, 32, or 64 in little-endian or big-endian.

getWord32le :: VGet Word32

getWord32be :: VGet Word32

getWord64le :: VGet Word64

getWord64be :: VGet Word64

getStorable :: Storable a => VGet a

Read a Storable value. In this case, the content should be bytes only, since pointers aren't really meaningful when persisted. Data is copied to an intermediate structure via alloca to avoid alignment issues.

getVarNat :: VGet Integer

Get a non-negative number represented in the Google protocol buffers varint encoding, e.g. as produced by putVarNat.

getVarInt :: VGet Integer

Get an integer represented in the Google protocol buffers zigzag varint encoding, e.g. as produced by putVarInt.

getByteString :: Int -> VGet ByteString

Load a number of bytes from the underlying object. A copy is performed in this case (typically no copy is performed by VGet, but the underlying pointer is ephemeral, becoming invalid after the current read transaction). Fails if not enough data. O(N)

getByteStringLazy :: Int -> VGet ByteString

Get a lazy bytestring. (Simple wrapper on strict bytestring.)

getc :: VGet Char

Get a character from UTF-8 format. Assumes a valid encoding. (In case of invalid encoding, arbitrary characters may be returned.)

zero copy access

withBytes :: Int -> (Ptr Word8 -> IO a) -> VGet a

Access a given number of bytes without copying them. These bytes are read-only, and are considered to be consumed upon returning. The pointer should be considered invalid after returning from the withBytes computation.

Parser Combinators

isolate :: Int -> Int -> VGet a -> VGet a

isolate a parser to a subset of bytes and value references. The child parser must process its entire input (all bytes and values) or will fail. If there is not enough available input to isolate, this operation will fail.

isolate nBytes nVRefs operation

label :: ShowS -> VGet a -> VGet a

label will modify the error message returned from the argument operation; it can help contextualize parse errors.

lookAhead :: VGet a -> VGet a

lookAhead will parse a value, but not consume any input.

lookAheadM :: VGet (Maybe a) -> VGet (Maybe a)

lookAheadM will consume input only if it returns `Just a`.

lookAheadE :: VGet (Either a b) -> VGet (Either a b)

lookAheadE will consume input only if it returns `Right b`.

isEmpty :: VGet Bool

isEmpty will return True iff there is no available input (neither references nor values).