store-core-0.4.4.7: Fast and lightweight binary serialization

Safe Haskell | None
Language | Haskell2010

Data.Store.Core

Contents

- Core Types
- Encode ByteString
- Decode ByteString
- Storable
- ForeignPtr
- ByteArray
- Creation of PokeState / PeekState

Synopsis

- newtype Poke a = Poke {
  - runPoke :: PokeState -> Offset -> IO (Offset, a)
  }
- data PokeException = PokeException {
  - pokeExByteIndex :: Offset
  - pokeExMessage :: Text
  }
- pokeException :: Text -> Poke a
- newtype Peek a = Peek {
  - runPeek :: PeekState -> Ptr Word8 -> IO (PeekResult a)
  }
- data PeekResult a = PeekResult !(Ptr Word8) !a
- data PeekException = PeekException {
  - peekExBytesFromEnd :: Offset
  - peekExMessage :: Text
  }
- peekException :: Text -> Peek a
- tooManyBytes :: Int -> Int -> String -> IO void
- data PokeState
- pokeStatePtr :: PokeState -> Ptr Word8
- data PeekState
- peekStateEndPtr :: PeekState -> Ptr Word8
- type Offset = Int
- unsafeEncodeWith :: Poke () -> Int -> ByteString
- decodeWith :: Peek a -> ByteString -> Either PeekException a
- decodeExWith :: Peek a -> ByteString -> a
- decodeExPortionWith :: Peek a -> ByteString -> (Offset, a)
- decodeIOWith :: Peek a -> ByteString -> IO a
- decodeIOPortionWith :: Peek a -> ByteString -> IO (Offset, a)
- decodeIOWithFromPtr :: Peek a -> Ptr Word8 -> Int -> IO a
- decodeIOPortionWithFromPtr :: Peek a -> Ptr Word8 -> Int -> IO (Offset, a)
- pokeStorable :: Storable a => a -> Poke ()
- peekStorable :: (Storable a, Typeable a) => Peek a
- peekStorableTy :: Storable a => String -> Peek a
- pokeFromForeignPtr :: ForeignPtr a -> Int -> Int -> Poke ()
- peekToPlainForeignPtr :: String -> Int -> Peek (ForeignPtr a)
- pokeFromPtr :: Ptr a -> Int -> Int -> Poke ()
- pokeFromByteArray :: ByteArray# -> Int -> Int -> Poke ()
- peekToByteArray :: String -> Int -> Peek ByteArray
- unsafeMakePokeState :: Ptr Word8 -> IO (Ptr Word8) -> IO PokeState
- unsafeMakePeekState :: Ptr Word8 -> IO (Ptr Word8) -> IO PeekState
- maybeAlignmentBufferSize :: Maybe Int

# Core Types

newtype Poke a Source #

`Poke` actions are useful for building sequential serializers.

They are actions which write values to bytes into memory specified by a `Ptr` base. The `Applicative` and `Monad` instances make it easy to write serializations, by keeping track of the `Offset` of the current byte. They allow you to chain `Poke` action such that subsequent `Poke`s write into subsequent portions of the output.

Constructors

Poke |

Fields

- runPoke :: PokeState -> Offset -> IO (Offset, a)

  Run the `Poke` action, with the `Ptr` to the buffer where data is poked, and the current `Offset`. The result is the new offset, along with a return value.

  May throw a `PokeException`, though this should be avoided when possible. They usually indicate a programming error.

#### Instances

Instances details

MonadIO Poke Source # |
Instance details Defined in Data.Store.Core Methods liftIO :: IO a -> Poke a Source #
Applicative Poke Source # |
Instance details Defined in Data.Store.Core Methods pure :: a -> Poke a Source # (<*>) :: Poke (a -> b) -> Poke a -> Poke b Source # liftA2 :: (a -> b -> c) -> Poke a -> Poke b -> Poke c Source # (*>) :: Poke a -> Poke b -> Poke b Source # (<*) :: Poke a -> Poke b -> Poke a Source #
Functor Poke Source # |
Instance details Defined in Data.Store.Core Methods fmap :: (a -> b) -> Poke a -> Poke b Source # (<$) :: a -> Poke b -> Poke a Source #
Monad Poke Source # |
Instance details Defined in Data.Store.Core Methods (>>=) :: Poke a -> (a -> Poke b) -> Poke b Source # (>>) :: Poke a -> Poke b -> Poke b Source # return :: a -> Poke a Source #
MonadFail Poke Source # |
Instance details Defined in Data.Store.Core Methods fail :: String -> Poke a Source #

data PokeException Source #

Exception thrown while running `poke`. Note that other types of exceptions could also be thrown. Invocations of `fail` in the `Poke` monad causes this exception to be thrown.

`PokeException`s are not expected to occur in ordinary circumstances, and usually indicate a programming error.

Constructors

PokeException |

Fields

- pokeExByteIndex :: Offset
- pokeExMessage :: Text

#### Instances

Instances details

Exception PokeException Source # |
Instance details Defined in Data.Store.Core Methods toException :: PokeException -> SomeException Source # fromException :: SomeException -> Maybe PokeException Source # displayException :: PokeException -> String Source # backtraceDesired :: PokeException -> Bool Source #
Show PokeException Source # |
Instance details Defined in Data.Store.Core Methods showsPrec :: Int -> PokeException -> ShowS Source # show :: PokeException -> String Source # showList :: [PokeException] -> ShowS Source #
Eq PokeException Source # |
Instance details Defined in Data.Store.Core Methods (==) :: PokeException -> PokeException -> Bool Source # (/=) :: PokeException -> PokeException -> Bool Source #

pokeException :: Text -> Poke a Source #

Throws a `PokeException`. These should be avoided when possible, they usually indicate a programming error.

newtype Peek a Source #

`Peek` actions are useful for building sequential deserializers.

They are actions which read from memory and construct values from it. The `Applicative` and `Monad` instances make it easy to chain these together to get more complicated deserializers. This machinery keeps track of the current `Ptr` and end-of-buffer `Ptr`.

Constructors

Peek |

Fields

- runPeek :: PeekState -> Ptr Word8 -> IO (PeekResult a)

  Run the `Peek` action, with a `Ptr` to the end of the buffer where data is poked, and a `Ptr` to the current position. The result is the `Ptr`, along with a return value.

  May throw a `PeekException` if the memory contains invalid values.

#### Instances

Instances details

MonadIO Peek Source # |
Instance details Defined in Data.Store.Core Methods liftIO :: IO a -> Peek a Source #
Applicative Peek Source # |
Instance details Defined in Data.Store.Core Methods pure :: a -> Peek a Source # (<*>) :: Peek (a -> b) -> Peek a -> Peek b Source # liftA2 :: (a -> b -> c) -> Peek a -> Peek b -> Peek c Source # (*>) :: Peek a -> Peek b -> Peek b Source # (<*) :: Peek a -> Peek b -> Peek a Source #
Functor Peek Source # |
Instance details Defined in Data.Store.Core Methods fmap :: (a -> b) -> Peek a -> Peek b Source # (<$) :: a -> Peek b -> Peek a Source #
Monad Peek Source # |
Instance details Defined in Data.Store.Core Methods (>>=) :: Peek a -> (a -> Peek b) -> Peek b Source # (>>) :: Peek a -> Peek b -> Peek b Source # return :: a -> Peek a Source #
MonadFail Peek Source # |
Instance details Defined in Data.Store.Core Methods fail :: String -> Peek a Source #
PrimMonad Peek Source # |

Instance details

Defined in Data.Store.Core

Associated Types

type PrimState Peek |
Instance details Defined in Data.Store.Core type PrimState Peek = RealWorld

Methods

primitive :: (State# (PrimState Peek) -> (# State# (PrimState Peek), a #)) -> Peek a Source #

type PrimState Peek Source # |
Instance details Defined in Data.Store.Core type PrimState Peek = RealWorld

data PeekResult a Source #

A result of a `Peek` action containing the current `Ptr` and a return value.

Constructors

PeekResult !(Ptr Word8) !a |

#### Instances

Instances details

Functor PeekResult Source # |
Instance details Defined in Data.Store.Core Methods fmap :: (a -> b) -> PeekResult a -> PeekResult b Source # (<$) :: a -> PeekResult b -> PeekResult a Source #

data PeekException Source #

Exception thrown while running `peek`. Note that other types of exceptions can also be thrown. Invocations of `fail` in the `Poke` monad causes this exception to be thrown.

`PeekException` is thrown when the data being decoded is invalid.

Constructors

PeekException |

Fields

- peekExBytesFromEnd :: Offset
- peekExMessage :: Text

#### Instances

Instances details

Exception PeekException Source # |
Instance details Defined in Data.Store.Core Methods toException :: PeekException -> SomeException Source # fromException :: SomeException -> Maybe PeekException Source # displayException :: PeekException -> String Source # backtraceDesired :: PeekException -> Bool Source #
Show PeekException Source # |
Instance details Defined in Data.Store.Core Methods showsPrec :: Int -> PeekException -> ShowS Source # show :: PeekException -> String Source # showList :: [PeekException] -> ShowS Source #
Eq PeekException Source # |
Instance details Defined in Data.Store.Core Methods (==) :: PeekException -> PeekException -> Bool Source # (/=) :: PeekException -> PeekException -> Bool Source #

peekException :: Text -> Peek a Source #

Throws a `PeekException`.

tooManyBytes :: Int -> Int -> String -> IO void Source #

Throws a `PeekException` about an attempt to read too many bytes.

data PokeState Source #

Holds a `pokeStatePtr`, which is passed in to each `Poke` action. If the package is built with the 'force-alignment' flag, this also has a hidden `Ptr` field, which is used as scratch space during unaligned writes.

pokeStatePtr :: PokeState -> Ptr Word8 Source #

data PeekState Source #

Holds a `peekStatePtr`, which is passed in to each `Peek` action. If the package is built with the 'force-alignment' flag, this also has a hidden `Ptr` field, which is used as scratch space during unaligned reads.

peekStateEndPtr :: PeekState -> Ptr Word8 Source #

type Offset = Int Source #

How far into the given Ptr to look

# Encode ByteString

unsafeEncodeWith :: Poke () -> Int -> ByteString Source #

Given a `Poke` and its length, uses it to fill a `ByteString`

This function is unsafe because the provided length must exactly match the number of bytes used by the `Poke`. It will throw `PokeException` errors when the buffer is under or overshot. However, in the case of overshooting the buffer, memory corruption and segfaults may occur.

# Decode ByteString

decodeWith :: Peek a -> ByteString -> Either PeekException a Source #

Decodes a value from a `ByteString`, potentially throwing exceptions, and taking a `Peek` to run. It is an exception to not consume all input.

decodeExWith :: Peek a -> ByteString -> a Source #

Decodes a value from a `ByteString`, potentially throwing exceptions, and taking a `Peek` to run. It is an exception to not consume all input.

decodeExPortionWith :: Peek a -> ByteString -> (Offset, a) Source #

Similar to `decodeExWith`, but it allows there to be more of the buffer remaining. The `Offset` of the buffer contents immediately after the decoded value is returned.

decodeIOWith :: Peek a -> ByteString -> IO a Source #

Decodes a value from a `ByteString`, potentially throwing exceptions, and taking a `Peek` to run. It is an exception to not consume all input.

decodeIOPortionWith :: Peek a -> ByteString -> IO (Offset, a) Source #

Similar to `decodeExPortionWith`, but runs in the `IO` monad.

decodeIOWithFromPtr :: Peek a -> Ptr Word8 -> Int -> IO a Source #

Like `decodeIOWith`, but using `Ptr` and length instead of a `ByteString`.

decodeIOPortionWithFromPtr :: Peek a -> Ptr Word8 -> Int -> IO (Offset, a) Source #

Like `decodeIOPortionWith`, but using `Ptr` and length instead of a `ByteString`.

# Storable

pokeStorable :: Storable a => a -> Poke () Source #

A `poke` implementation based on an instance of `Storable`.

peekStorable :: (Storable a, Typeable a) => Peek a Source #

A `peek` implementation based on an instance of `Storable` and `Typeable`.

peekStorableTy :: Storable a => String -> Peek a Source #

A `peek` implementation based on an instance of `Storable`. Use this if the type is not `Typeable`.

# ForeignPtr

pokeFromForeignPtr :: ForeignPtr a -> Int -> Int -> Poke () Source #

Copy a section of memory, based on a `ForeignPtr`, to the output. Note that this operation is unsafe, the offset and length parameters are not checked.

peekToPlainForeignPtr :: String -> Int -> Peek (ForeignPtr a) Source #

Allocate a plain ForeignPtr (no finalizers), of the specified length and fill it with bytes from the input.

pokeFromPtr :: Ptr a -> Int -> Int -> Poke () Source #

Copy a section of memory, based on a `Ptr`, to the output. Note that this operation is unsafe, because the offset and length parameters are not checked.

# ByteArray

pokeFromByteArray :: ByteArray# -> Int -> Int -> Poke () Source #

Copy a section of memory, based on a `ByteArray#`, to the output. Note that this operation is unsafe, because the offset and length parameters are not checked.

peekToByteArray :: String -> Int -> Peek ByteArray Source #

Allocate a ByteArray of the specified length and fill it with bytes from the input.

# Creation of PokeState / PeekState

unsafeMakePokeState Source #

Arguments

:: Ptr Word8 | pokeStatePtr
-> IO (Ptr Word8) | action to produce pokeStateAlignPtr
-> IO PokeState |

Make a `PokeState` from a buffer pointer.

The first argument is a pointer to the memory to write to. The second argument is an IO action which is invoked if the store-core package was built with the `force-alignment` flag. The action should yield a pointer to scratch memory as large as `maybeAlignmentBufferSize`.

Since 0.4.2

unsafeMakePeekState Source #

Arguments

:: Ptr Word8 | peekStateEndPtr
-> IO (Ptr Word8) | action to produce peekStateAlignPtr
-> IO PeekState |

Make a `PeekState` from a buffer pointer.

The first argument is a pointer to the memory to write to. The second argument is an IO action which is invoked if the store-core package was built with the `force-alignment` flag. The action should yield a pointer to scratch memory as large as `maybeAlignmentBufferSize`.

Since 0.4.2

maybeAlignmentBufferSize :: Maybe Int Source #

If store-core is built with the `force-alignment` flag, then this will be a `Just` value indicating the amount of memory that is expected in the alignment buffer used by `PeekState` and `PokeState`. Currently this will either be `Just 32` or `Nothing`.