| Copyright | (c) Alexey Kuleshevich 2024 |
|---|---|
| License | BSD3 |
| Maintainer | Alexey Kuleshevich <alexey@kuleshevi.ch> |
| Stability | experimental |
| Portability | non-portable |
| Safe Haskell | Safe-Inferred |
| Language | Haskell2010 |
Data.MemPack
Description
Synopsis
- newtype Pack s a = Pack {
- runPack :: MutableByteArray s -> StateT Int (ST s) a
- newtype Unpack b a = Unpack {}
- class MemPack a where
- pack :: forall a. (MemPack a, HasCallStack) => a -> ByteArray
- packByteArray :: forall a. (MemPack a, HasCallStack) => Bool -> a -> ByteArray
- packByteString :: forall a. (MemPack a, HasCallStack) => a -> ByteString
- packShortByteString :: forall a. (MemPack a, HasCallStack) => a -> ShortByteString
- packMutableByteArray :: forall a s. (MemPack a, HasCallStack) => Bool -> a -> ST s (MutableByteArray s)
- packIncrement :: MemPack a => a -> Pack s Int
- guardAdvanceUnpack :: Buffer b => Int -> Unpack b Int
- unpack :: forall a b. (MemPack a, Buffer b, HasCallStack) => b -> Either SomeError a
- unpackFail :: forall a b. (MemPack a, Buffer b, HasCallStack) => b -> Fail SomeError a
- unpackMonadFail :: forall a b m. (MemPack a, Buffer b, MonadFail m) => b -> m a
- unpackError :: forall a b. (MemPack a, Buffer b, HasCallStack) => b -> a
- unpackLeftOver :: forall a b. (MemPack a, Buffer b, HasCallStack) => b -> Fail SomeError (a, Int)
- failUnpack :: Error e => e -> Unpack b a
- unpackByteArray :: Buffer b => Bool -> Unpack b ByteArray
- newtype VarLen a = VarLen {
- unVarLen :: a
- newtype Length = Length {}
- newtype Tag = Tag {}
- packTagM :: Tag -> Pack s ()
- unpackTagM :: Buffer b => Unpack b Tag
- unknownTagM :: forall a m b. (MemPack a, MonadFail m) => Tag -> m b
- packedTagByteCount :: Int
- replicateTailM :: Monad m => Int -> m a -> m [a]
- lift_# :: (State# s -> State# s) -> Pack s ()
- st_ :: (State# s -> State# s) -> ST s ()
- newtype StateT s (m :: Type -> Type) a = StateT {
- runStateT :: s -> m (a, s)
- newtype FailT e (m :: Type -> Type) a = FailT (m (Either [e] a))
Documentation
Monad that is used for serializing data into a MutableByteArray. It is based on
StateT that tracks the current index into the MutableByteArray where next write is
expected to happen.
Instances
| MonadState Int (Pack s) Source # | |
| Applicative (Pack s) Source # | |
| Functor (Pack s) Source # | |
| Monad (Pack s) Source # | |
| MonadReader (MutableByteArray s) (Pack s) Source # | |
Defined in Data.MemPack Methods ask :: Pack s (MutableByteArray s) # local :: (MutableByteArray s -> MutableByteArray s) -> Pack s a -> Pack s a # reader :: (MutableByteArray s -> a) -> Pack s a # | |
Monad that is used for deserializing data from a memory Buffer. It is based on
StateT that tracks the current index into the Buffer afail with MonadFail instance or with
failUnpack that provides a more type safe way of failing using Error interface.
class MemPack a where Source #
Efficient serialization interface that operates directly on memory buffers.
Minimal complete definition
Methods
Name of the type that is being deserialized for error reporting. Default
implementation relies on Typeable.
packedByteCount :: a -> Int Source #
Report the exact size in number of bytes that packed version of this type will
occupy. It is very important to get this right, otherwise packM will result in a
runtime exception. Another words this is the expected property that it should hold:
packedByteCount a == bufferByteCount (pack a)
packM :: a -> Pack s () Source #
Write binary representation of a type into the MutableByteArray which can be
accessed with ask, whenever direct operations on it are necessary.
unpackM :: Buffer b => Unpack b a Source #
Read binary representation of the type directly from the buffer, which can be
accessed with ask when necessary. Direct reads from the buffer should be preceded
with advancing the buffer offset with MonadState by the number of bytes that will
be consumed from the buffer and making sure that no reads outside of the buffer can
happen. Violation of these rules will lead to segfaults.
Instances
Packing
pack :: forall a. (MemPack a, HasCallStack) => a -> ByteArray Source #
Serialize a type into an unpinned ByteArray
Examples
>>>:set -XTypeApplications>>>unpack @[Int] $ pack ([1,2,3,4,5] :: [Int])Right [1,2,3,4,5]
Arguments
| :: forall a. (MemPack a, HasCallStack) | |
| => Bool | Should the array be allocated in pinned memory? |
| -> a | |
| -> ByteArray |
Same as pack, but allows controlling the pinnedness of allocated memory
packByteString :: forall a. (MemPack a, HasCallStack) => a -> ByteString Source #
Serialize a type into a pinned ByteString
packShortByteString :: forall a. (MemPack a, HasCallStack) => a -> ShortByteString Source #
Serialize a type into an unpinned ShortByteString
Arguments
| :: forall a s. (MemPack a, HasCallStack) | |
| => Bool | Should the array be allocated in pinned memory? |
| -> a | |
| -> ST s (MutableByteArray s) |
Same as packByteArray, but produces a mutable array instead
Helpers
packIncrement :: MemPack a => a -> Pack s Int Source #
Increment the offset counter of Pack monad by then number of packedByteCount and
return the starting offset.
guardAdvanceUnpack :: Buffer b => Int -> Unpack b Int Source #
Increment the offset counter of Unpack monad by the supplied number of
bytes. Returns the original offset or fails with RanOutOfBytesError whenever there is
not enough bytes in the Buffer.
Unpacking
unpack :: forall a b. (MemPack a, Buffer b, HasCallStack) => b -> Either SomeError a Source #
Unpack a memory Buffer into a type using its MemPack instance. Besides potential
unpacking failures due to a malformed buffer it will also fail the supplied Buffer
was not fully consumed. Use unpackLeftOver, whenever a partially consumed buffer is
possible.
unpackFail :: forall a b. (MemPack a, Buffer b, HasCallStack) => b -> Fail SomeError a Source #
unpackMonadFail :: forall a b m. (MemPack a, Buffer b, MonadFail m) => b -> m a Source #
Same as unpackFail except fails in any MonadFail, instead of Fail.
unpackError :: forall a b. (MemPack a, Buffer b, HasCallStack) => b -> a Source #
Same as unpack except throws a runtime exception upon a failure
unpackLeftOver :: forall a b. (MemPack a, Buffer b, HasCallStack) => b -> Fail SomeError (a, Int) Source #
Helpers
unpackByteArray :: Buffer b => Bool -> Unpack b ByteArray Source #
This is the implementation of unpackM for ByteArray and ByteString
Helper packers
Variable length encoding for bounded types. This type of encoding will use less memory for small values, but for larger values it will consume more memory and will be slower during packing/unpacking.
Instances
This is a helper type useful for serializing number of elements in data
structures. It uses VarLen underneath, since sizes of common data structures aren't
too big. It also prevents negative values from being serialized and deserialized.
This is a helper type that is useful for creating MemPack instances for sum types.
Internal utilities
replicateTailM :: Monad m => Int -> m a -> m [a] Source #
Tail recursive version of replicateM
Re-exports for GeneralizedNewtypeDeriving
newtype StateT s (m :: Type -> Type) a #
A state transformer monad parameterized by:
s- The state.m- The inner monad.
The return function leaves the state unchanged, while >>= uses
the final state of the first computation as the initial state of
the second.
Instances
| MonadReader r m => MonadReader r (StateT s m) | |
| Monad m => MonadState s (StateT s m) | |
| MonadTrans (StateT s) | |
Defined in Control.Monad.Trans.State.Strict | |
| MonadFail m => MonadFail (StateT s m) | |
Defined in Control.Monad.Trans.State.Strict | |
| MonadFix m => MonadFix (StateT s m) | |
Defined in Control.Monad.Trans.State.Strict | |
| MonadIO m => MonadIO (StateT s m) | |
Defined in Control.Monad.Trans.State.Strict | |
| Contravariant m => Contravariant (StateT s m) | |
| (Functor m, MonadPlus m) => Alternative (StateT s m) | |
| (Functor m, Monad m) => Applicative (StateT s m) | |
Defined in Control.Monad.Trans.State.Strict | |
| Functor m => Functor (StateT s m) | |
| Monad m => Monad (StateT s m) | |
| MonadPlus m => MonadPlus (StateT s m) | |
| Generic (StateT s m a) | |
| type Rep (StateT s m a) | |
Defined in Control.Monad.Trans.State.Strict | |
newtype FailT e (m :: Type -> Type) a #
Fail monad transformer that plays well with MonadFail type class.
Instances
| MonadRWS r w s m => MonadRWS r w s (FailT e m) | Since: FailT-0.1.1 |
Defined in Control.Monad.Trans.Fail | |
| MonadAccum w m => MonadAccum w (FailT e m) | Since: FailT-0.1.1 |
| MonadError e m => MonadError e (FailT e m) | |
Defined in Control.Monad.Trans.Fail Methods throwError :: e -> FailT e m a # catchError :: FailT e m a -> (e -> FailT e m a) -> FailT e m a # | |
| MonadReader r m => MonadReader r (FailT e m) | |
| MonadSelect r m => MonadSelect r (FailT e m) | Since: FailT-0.1.1 |
Defined in Control.Monad.Trans.Fail | |
| MonadState s m => MonadState s (FailT e m) | |
| MonadWriter w m => MonadWriter w (FailT e m) | |
| MonadTrans (FailT e) | |
Defined in Control.Monad.Trans.Fail | |
| (IsString e, Monad m) => MonadFail (FailT e m) | |
Defined in Control.Monad.Trans.Fail | |
| MonadFix m => MonadFix (FailT e m) | |
Defined in Control.Monad.Trans.Fail | |
| MonadIO m => MonadIO (FailT e m) | |
Defined in Control.Monad.Trans.Fail | |
| MonadZip m => MonadZip (FailT e m) | |
| Foldable f => Foldable (FailT e f) | |
Defined in Control.Monad.Trans.Fail Methods fold :: Monoid m => FailT e f m -> m # foldMap :: Monoid m => (a -> m) -> FailT e f a -> m # foldMap' :: Monoid m => (a -> m) -> FailT e f a -> m # foldr :: (a -> b -> b) -> b -> FailT e f a -> b # foldr' :: (a -> b -> b) -> b -> FailT e f a -> b # foldl :: (b -> a -> b) -> b -> FailT e f a -> b # foldl' :: (b -> a -> b) -> b -> FailT e f a -> b # foldr1 :: (a -> a -> a) -> FailT e f a -> a # foldl1 :: (a -> a -> a) -> FailT e f a -> a # toList :: FailT e f a -> [a] # length :: FailT e f a -> Int # elem :: Eq a => a -> FailT e f a -> Bool # maximum :: Ord a => FailT e f a -> a # minimum :: Ord a => FailT e f a -> a # | |
| (Eq e, Eq1 m) => Eq1 (FailT e m) | |
| (Ord e, Ord1 m) => Ord1 (FailT e m) | |
Defined in Control.Monad.Trans.Fail | |
| (Read e, Read1 m) => Read1 (FailT e m) | |
Defined in Control.Monad.Trans.Fail | |
| (Show e, Show1 m) => Show1 (FailT e m) | |
| Contravariant f => Contravariant (FailT e f) | |
| Traversable f => Traversable (FailT e f) | |
Defined in Control.Monad.Trans.Fail | |
| Monad m => Alternative (FailT e m) | Short-circuits on the first successful operation, combines failures otherwise. |
| Monad m => Applicative (FailT e m) | |
Defined in Control.Monad.Trans.Fail | |
| Functor m => Functor (FailT e m) | |
| Monad m => Monad (FailT e m) | Short-circuites on the first failing operation. |
| MonadThrow m => MonadThrow (FailT e m) | |
Defined in Control.Monad.Trans.Fail Methods throwM :: (HasCallStack, Exception e0) => e0 -> FailT e m a # | |
| MonadCont m => MonadCont (FailT e m) | |
| (Monad m, Semigroup a) => Monoid (FailT e m a) | |
| (Monad m, Semigroup a) => Semigroup (FailT e m a) | Executes all monadic actions and combines all successful results using a |
| (Read e, Read1 m, Read a) => Read (FailT e m a) | |
| (Show e, Show1 m, Show a) => Show (FailT e m a) | |
| (Eq e, Eq1 m, Eq a) => Eq (FailT e m a) | |
| (Ord e, Ord1 m, Ord a) => Ord (FailT e m a) | |
Defined in Control.Monad.Trans.Fail | |