| Safe Haskell | None |
|---|---|
| Language | Haskell2010 |
Data.Store
Description
This is the main public API of the store package. The functions exported here are more likely to be stable between versions.
Usually you won't need to write your own Store instances, and
instead can rely on either using the Generic deriving approach or
Data.Store.TH for defining Store instances for your datatypes.
There are some tradeoffs here - the generics instances do not require
-XTemplateHaskell, but they do not optimize as well for sum types
that only require a constant number of bytes.
If you need streaming encode / decode of multiple store encoded
messages, take a look at the store-streaming package.
Gotchas
Store is best used for communication between trusted processes and local caches. It can certainly be used for other purposes, but the builtin set of instances have some gotchas to be aware of:
- Store's builtin instances serialize in a format which depends on machine endianness.
- Store's builtin instances trust the data when deserializing. For
example, the deserialization of
Vectorwill read the vector's link from the first 8 bytes. It will then allocate enough memory to store all the elements. Malicious or malformed input could cause allocation of large amounts of memory. See https://github.com/fpco/store/issues/122
Synopsis
- encode :: Store a => a -> ByteString
- decode :: Store a => ByteString -> Either PeekException a
- decodeWith :: Peek a -> ByteString -> Either PeekException a
- decodeEx :: Store a => ByteString -> a
- decodeExWith :: Peek a -> ByteString -> a
- decodeExPortionWith :: Peek a -> ByteString -> (Offset, a)
- decodeIO :: Store a => ByteString -> IO a
- decodeIOWith :: Peek a -> ByteString -> IO a
- decodeIOPortionWith :: Peek a -> ByteString -> IO (Offset, a)
- class Store a where
- data Size a
- data Poke a
- data Peek a
- class GStoreSize (f :: Type -> Type)
- class GStorePoke (f :: Type -> Type)
- class GStorePeek (f :: Type -> Type)
- data PeekException = PeekException {
- peekExBytesFromEnd :: Offset
- peekExMessage :: Text
- peekException :: Text -> Peek a
Encoding and decoding strict ByteStrings.
encode :: Store a => a -> ByteString Source #
Serializes a value to a ByteString. In order to do this, it
first allocates a ByteString of the correct size (based on
size), and then uses poke to fill it.
Safety of this function depends on correctness of the Store
instance. If size returns a. The good news is that this isn't an
issue if you use well-tested manual instances (such as those from
this package) combined with auomatic definition of instances.
decode :: Store a => ByteString -> Either PeekException a Source #
Decodes a value from a ByteString. Returns an exception if
there's an error while decoding, or if decoding undershoots /
overshoots the end of the buffer.
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.
decodeEx :: Store a => ByteString -> a Source #
Decodes a value from a ByteString, potentially throwing
exceptions. 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.
decodeIO :: Store a => ByteString -> IO a Source #
Decodes a value from a ByteString, potentially throwing
exceptions. It is an exception to not consume all input.
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.
Store class and related types.
The Store typeclass provides efficient serialization and
deserialization to raw pointer addresses.
The peek and poke methods should be defined such that
decodeEx (encode x) == x .
Minimal complete definition
Nothing
Methods
Yields the Size of the buffer, in bytes, required to store
the encoded representation of the type.
Note that the correctness of this function is crucial for the
safety of poke, as it does not do any bounds checking. It is
the responsibility of the invoker of poke (encode and similar
functions) to ensure that there's enough space in the output
buffer. If poke writes beyond, then arbitrary memory can be
overwritten, causing undefined behavior and segmentation faults.
default size :: (Generic a, GStoreSize (Rep a)) => Size a Source #
Serializes a value to bytes. It is the responsibility of the
caller to ensure that at least the number of bytes required by
size are available. These details are handled by encode and
similar utilities.
default poke :: (Generic a, GStorePoke (Rep a)) => a -> Poke () Source #
Serialized a value from bytes, throwing exceptions if it encounters invalid data or runs out of input bytes.
default peek :: (Generic a, GStorePeek (Rep a)) => Peek a Source #
Instances
| Store ByteString Source # | |
| Store ByteString Source # | |
| Store ShortByteString Source # | |
| Store IntSet Source # | |
| Store Void Source # | |
| Store All Source # | |
| Store Any Source # | |
| Store Fingerprint Source # | |
| Store CBool Source # | |
| Store CChar Source # | |
| Store CClock Source # | |
| Store CDouble Source # | |
| Store CFloat Source # | |
| Store CInt Source # | |
| Store CIntMax Source # | |
| Store CIntPtr Source # | |
| Store CLLong Source # | |
| Store CLong Source # | |
| Store CPtrdiff Source # | |
| Store CSChar Source # | |
| Store CSUSeconds Source # | |
| Store CShort Source # | |
| Store CSigAtomic Source # | |
| Store CSize Source # | |
| Store CTime Source # | |
| Store CUChar Source # | |
| Store CUInt Source # | |
| Store CUIntMax Source # | |
| Store CUIntPtr Source # | |
| Store CULLong Source # | |
| Store CULong Source # | |
| Store CUSeconds Source # | |
| Store CUShort Source # | |
| Store CWchar Source # | |
| Store IntPtr Source # | |
| Store WordPtr Source # | |
| Store Int16 Source # | |
| Store Int32 Source # | |
| Store Int64 Source # | |
| Store Int8 Source # | |
| Store IoSubSystem Source # | |
| Store CBlkCnt Source # | |
| Store CBlkSize Source # | |
| Store CCc Source # | |
| Store CClockId Source # | |
| Store CDev Source # | |
| Store CFsBlkCnt Source # | |
| Store CFsFilCnt Source # | |
| Store CGid Source # | |
| Store CId Source # | |
| Store CIno Source # | |
| Store CKey Source # | |
| Store CMode Source # | |
| Store CNfds Source # | |
| Store CNlink Source # | |
| Store COff Source # | |
| Store CPid Source # | |
| Store CRLim Source # | |
| Store CSocklen Source # | |
| Store CSpeed Source # | |
| Store CSsize Source # | |
| Store CTcflag Source # | |
| Store CTimer Source # | |
| Store CUid Source # | |
| Store Fd Source # | |
| Store Word16 Source # | |
| Store Word32 Source # | |
| Store Word64 Source # | |
| Store Word8 Source # | |
| Store PortNumber Source # | |
Defined in Data.Store.Internal Methods size :: Size PortNumber Source # poke :: PortNumber -> Poke () Source # peek :: Peek PortNumber Source # | |
| Store TypeHash Source # | |
| Store StoreVersion Source # | |
Defined in Data.Store.Version Methods size :: Size StoreVersion Source # poke :: StoreVersion -> Poke () Source # peek :: Peek StoreVersion Source # | |
| Store AnnTarget Source # | |
| Store Bang Source # | |
| Store BndrVis Source # | |
| Store Body Source # | |
| Store Bytes Source # | Template Haskell Bytes are nearly identical to ByteString, but it can't depend on ByteString. |
| Store Callconv Source # | |
| Store Clause Source # | |
| Store Con Source # | |
| Store Dec Source # | |
| Store DerivClause Source # | |
| Store DerivStrategy Source # | |
| Store Exp Source # | |
| Store FamilyResultSig Source # | |
| Store Fixity Source # | |
| Store FixityDirection Source # | |
| Store Foreign Source # | |
| Store FunDep Source # | |
| Store Guard Source # | |
| Store Info Source # | |
| Store InjectivityAnn Source # | |
| Store Inline Source # | |
| Store Lit Source # | |
| Store Match Source # | |
| Store ModName Source # | |
| Store Name Source # | |
| Store NameFlavour Source # | |
| Store NameSpace Source # | |
| Store NamespaceSpecifier Source # | |
| Store OccName Source # | |
| Store Overlap Source # | |
| Store Pat Source # | |
| Store PatSynArgs Source # | |
| Store PatSynDir Source # | |
| Store Phases Source # | |
| Store PkgName Source # | |
| Store Pragma Source # | |
| Store Range Source # | |
| Store Role Source # | |
| Store RuleBndr Source # | |
| Store RuleMatch Source # | |
| Store Safety Source # | |
| Store SourceStrictness Source # | |
| Store SourceUnpackedness Source # | |
| Store Specificity Source # | |
| Store Stmt Source # | |
| Store TyLit Source # | |
| Store TySynEqn Source # | |
| Store Type Source # | |
| Store TypeFamilyHead Source # | |
| Store Text Source # | |
| Store CalendarDiffDays Source # | |
| Store Day Source # | |
| Store Quarter Source # | |
| Store QuarterOfYear Source # | |
| Store DayOfWeek Source # | |
| Store FirstWeekType Source # | |
| Store AbsoluteTime Source # | |
| Store DiffTime Source # | |
| Store NominalDiffTime Source # | |
| Store SystemTime Source # | |
| Store UTCTime Source # | |
| Store UniversalTime Source # | |
| Store FormatExtension Source # | |
| Store TimeLocale Source # | |
| Store CalendarDiffTime Source # | |
| Store LocalTime Source # | |
| Store TimeOfDay Source # | |
| Store TimeZone Source # | |
| Store ZonedTime Source # | |
| Store Integer Source # | |
| Store Natural Source # | |
| Store () Source # | |
| Store Bool Source # | |
| Store Char Source # | |
| Store Double Source # | |
| Store Float Source # | |
| Store Int Source # | |
| Store Word Source # | |
| Store a => Store (Complex a) Source # | |
| Store a => Store (IntMap a) Source # | |
| Store a => Store (Seq a) Source # | |
| (Store a, Ord a) => Store (Set a) Source # | |
| Store a => Store (NonEmpty a) Source # | |
| Store a => Store (Identity a) Source # | |
| Store a => Store (First a) Source # | |
| Store a => Store (Last a) Source # | |
| Store a => Store (Dual a) Source # | |
| Store a => Store (Product a) Source # | |
| Store a => Store (Sum a) Source # | |
| Store (ConstPtr a) Source # | |
| Store (FunPtr a) Source # | |
| Store (Ptr a) Source # | |
| Store a => Store (Ratio a) Source # | |
| Store (StablePtr a) Source # | |
| Prim a => Store (PrimStorable a) Source # | |
Defined in Data.Store.Internal Methods size :: Size (PrimStorable a) Source # poke :: PrimStorable a -> Poke () Source # peek :: Peek (PrimStorable a) Source # | |
| (Store a, HasTypeHash a) => Store (Tagged a) Source # | |
| Store flag => Store (TyVarBndr flag) Source # | |
| (Eq a, Hashable a, Store a) => Store (HashSet a) Source # | |
| Store a => Store (Vector a) Source # | |
| Prim a => Store (Vector (Complex a)) Source # | |
| Prim a => Store (Vector (First a)) Source # | |
| Prim a => Store (Vector (Last a)) Source # | |
| Prim a => Store (Vector (Max a)) Source # | |
| Prim a => Store (Vector (Min a)) Source # | |
| Prim a => Store (Vector (Const a b)) Source # | |
| Prim a => Store (Vector (Identity a)) Source # | |
| Prim a => Store (Vector (Down a)) Source # | |
| Prim a => Store (Vector (Dual a)) Source # | |
| Prim a => Store (Vector (Product a)) Source # | |
| Prim a => Store (Vector (Sum a)) Source # | |
| Store (Vector CBool) Source # | |
| Store (Vector CChar) Source # | |
| Store (Vector CClock) Source # | |
| Store (Vector CDouble) Source # | |
| Store (Vector CFloat) Source # | |
| Store (Vector CInt) Source # | |
| Store (Vector CIntMax) Source # | |
| Store (Vector CIntPtr) Source # | |
| Store (Vector CLLong) Source # | |
| Store (Vector CLong) Source # | |
| Store (Vector CPtrdiff) Source # | |
| Store (Vector CSChar) Source # | |
| Store (Vector CSUSeconds) Source # | |
| Store (Vector CShort) Source # | |
| Store (Vector CSigAtomic) Source # | |
| Store (Vector CSize) Source # | |
| Store (Vector CTime) Source # | |
| Store (Vector CUChar) Source # | |
| Store (Vector CUInt) Source # | |
| Store (Vector CUIntMax) Source # | |
| Store (Vector CUIntPtr) Source # | |
| Store (Vector CULLong) Source # | |
| Store (Vector CULong) Source # | |
| Store (Vector CUSeconds) Source # | |
| Store (Vector CUShort) Source # | |
| Store (Vector CWchar) Source # | |
| Store (Vector IntPtr) Source # | |
| Store (Vector WordPtr) Source # | |
| Store (Vector Int16) Source # | |
| Store (Vector Int32) Source # | |
| Store (Vector Int64) Source # | |
| Store (Vector Int8) Source # | |
| Store (Vector (FunPtr a)) Source # | |
| Store (Vector (Ptr a)) Source # | |
| Store (Vector (StablePtr a)) Source # | |
| Store (Vector CBlkCnt) Source # | |
| Store (Vector CBlkSize) Source # | |
| Store (Vector CCc) Source # | |
| Store (Vector CClockId) Source # | |
| Store (Vector CDev) Source # | |
| Store (Vector CFsBlkCnt) Source # | |
| Store (Vector CFsFilCnt) Source # | |
| Store (Vector CGid) Source # | |
| Store (Vector CId) Source # | |
| Store (Vector CIno) Source # | |
| Store (Vector CKey) Source # | |
| Store (Vector CMode) Source # | |
| Store (Vector CNlink) Source # | |
| Store (Vector COff) Source # | |
| Store (Vector CPid) Source # | |
| Store (Vector CRLim) Source # | |
| Store (Vector CSpeed) Source # | |
| Store (Vector CSsize) Source # | |
| Store (Vector CTcflag) Source # | |
| Store (Vector CTimer) Source # | |
| Store (Vector CUid) Source # | |
| Store (Vector Fd) Source # | |
| Store (Vector Word16) Source # | |
| Store (Vector Word32) Source # | |
| Store (Vector Word64) Source # | |
| Store (Vector Word8) Source # | |
| Store (Vector Char) Source # | |
| Store (Vector Double) Source # | |
| Store (Vector Float) Source # | |
| Store (Vector Int) Source # | |
| Store (Vector Word) Source # | |
| Storable a => Store (Vector a) Source # | |
| Store a => Store (Vector a) Source # | |
| Store a => Store (DoNotUnboxLazy a) Source # | |
| Store a => Store (DoNotUnboxNormalForm a) Source # | |
| Store a => Store (DoNotUnboxStrict a) Source # | |
| Store (Vector a) => Store (Vector (Complex a)) Source # | |
| Store (Vector (f (g a))) => Store (Vector (Compose f g a)) Source # | |
| (Store (Vector a), Store (Vector b)) => Store (Vector (Arg a b)) Source # | |
| Store (Vector a) => Store (Vector (First a)) Source # | |
| Store (Vector a) => Store (Vector (Last a)) Source # | |
| Store (Vector a) => Store (Vector (Max a)) Source # | |
| Store (Vector a) => Store (Vector (Min a)) Source # | |
| Store (Vector a) => Store (Vector (WrappedMonoid a)) Source # | |
| Store (Vector a) => Store (Vector (Const a b)) Source # | |
| Store (Vector a) => Store (Vector (Identity a)) Source # | |
| Store (Vector a) => Store (Vector (Down a)) Source # | |
| Store (Vector All) Source # | |
| Store (Vector (f a)) => Store (Vector (Alt f a)) Source # | |
| Store (Vector Any) Source # | |
| Store (Vector a) => Store (Vector (Dual a)) Source # | |
| Store (Vector a) => Store (Vector (Product a)) Source # | |
| Store (Vector a) => Store (Vector (Sum a)) Source # | |
| Store (Vector Int16) Source # | |
| Store (Vector Int32) Source # | |
| Store (Vector Int64) Source # | |
| Store (Vector Int8) Source # | |
| Store (Vector Word16) Source # | |
| Store (Vector Word32) Source # | |
| Store (Vector Word64) Source # | |
| Store (Vector Word8) Source # | |
| Store a => Store (Vector (DoNotUnboxLazy a)) Source # | |
| Store a => Store (Vector (DoNotUnboxNormalForm a)) Source # | |
| Store a => Store (Vector (DoNotUnboxStrict a)) Source # | |
| (Store (Vector a), Store (Vector b)) => Store (Vector (a, b)) Source # | |
| (Store (Vector a), Store (Vector b), Store (Vector c)) => Store (Vector (a, b, c)) Source # | |
| (Store (Vector a), Store (Vector b), Store (Vector c), Store (Vector d)) => Store (Vector (a, b, c, d)) Source # | |
| (Store (Vector a), Store (Vector b), Store (Vector c), Store (Vector d), Store (Vector e)) => Store (Vector (a, b, c, d, e)) Source # | |
| (Store (Vector a), Store (Vector b), Store (Vector c), Store (Vector d), Store (Vector e), Store (Vector f)) => Store (Vector (a, b, c, d, e, f)) Source # | |
| Store (Vector ()) Source # | |
| Store (Vector Bool) Source # | |
| Store (Vector Char) Source # | |
| Store (Vector Double) Source # | |
| Store (Vector Float) Source # | |
| Store (Vector Int) Source # | |
| Store (Vector Word) Source # | |
| Store a => Store (Maybe a) Source # | |
| Store a => Store [a] Source # | |
| (Ix i, IArray UArray e, Store i, Store e) => Store (UArray i e) Source # | |
| Store (Fixed a) Source # | |
| (Ord k, Store k, Store a) => Store (Map k a) Source # | |
| (Ix i, Store i, Store e) => Store (Array i e) Source # | |
| (Store a, Store b) => Store (Either a b) Source # | |
| KnownNat n => Store (StaticSize n ByteString) Source # | |
Defined in Data.Store.Internal Methods size :: Size (StaticSize n ByteString) Source # poke :: StaticSize n ByteString -> Poke () Source # peek :: Peek (StaticSize n ByteString) Source # | |
| (Eq k, Hashable k, Store k, Store a) => Store (HashMap k a) Source # | |
| (Store a, Store b) => Store (a, b) Source # | |
| Store a => Store (Const a b) Source # | |
| (Store a, Store b, Store c) => Store (a, b, c) Source # | |
| (Store a, Store b, Store c, Store d) => Store (a, b, c, d) Source # | |
| (Store a, Store b, Store c, Store d, Store e) => Store (a, b, c, d, e) Source # | |
| (Store a, Store b, Store c, Store d, Store e, Store f) => Store (a, b, c, d, e, f) Source # | |
| (Store a, Store b, Store c, Store d, Store e, Store f, Store g) => Store (a, b, c, d, e, f, g) Source # | |
Info about a type's serialized length. Either the length is known independently of the value, or the length depends on the value.
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
Pokes write into subsequent portions of the output.
Instances
| MonadIO Poke | |
Defined in Data.Store.Core | |
| Applicative Poke | |
| Functor Poke | |
| Monad Poke | |
| MonadFail Poke | |
Defined in Data.Store.Core | |
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.
Instances
| MonadIO Peek | |
Defined in Data.Store.Core | |
| Applicative Peek | |
| Functor Peek | |
| Monad Peek | |
| MonadFail Peek | |
Defined in Data.Store.Core | |
| PrimMonad Peek | |
| type PrimState Peek | |
Defined in Data.Store.Core | |
class GStoreSize (f :: Type -> Type) Source #
Minimal complete definition
gsize
Instances
| GStoreSize (U1 :: Type -> Type) Source # | |
Defined in Data.Store.Impl | |
| GStoreSize (V1 :: Type -> Type) Source # | |
Defined in Data.Store.Impl | |
| (GStoreSize a, GStoreSize b) => GStoreSize (a :*: b) Source # | |
Defined in Data.Store.Impl | |
| (FitsInByte (SumArity (a :+: b)), GStoreSizeSum 0 (a :+: b)) => GStoreSize (a :+: b) Source # | |
Defined in Data.Store.Impl | |
| Store a => GStoreSize (K1 i a :: Type -> Type) Source # | |
Defined in Data.Store.Impl | |
| GStoreSize f => GStoreSize (M1 i c f) Source # | |
Defined in Data.Store.Impl | |
class GStorePoke (f :: Type -> Type) Source #
Minimal complete definition
gpoke
Instances
| GStorePoke (U1 :: Type -> Type) Source # | |
Defined in Data.Store.Impl | |
| GStorePoke (V1 :: Type -> Type) Source # | |
Defined in Data.Store.Impl | |
| (GStorePoke a, GStorePoke b) => GStorePoke (a :*: b) Source # | |
Defined in Data.Store.Impl | |
| (FitsInByte (SumArity (a :+: b)), GStorePokeSum 0 (a :+: b)) => GStorePoke (a :+: b) Source # | |
Defined in Data.Store.Impl | |
| Store a => GStorePoke (K1 i a :: Type -> Type) Source # | |
Defined in Data.Store.Impl | |
| GStorePoke f => GStorePoke (M1 i c f) Source # | |
Defined in Data.Store.Impl | |
class GStorePeek (f :: Type -> Type) Source #
Minimal complete definition
gpeek
Instances
| GStorePeek (U1 :: Type -> Type) Source # | |
Defined in Data.Store.Impl | |
| GStorePeek (V1 :: Type -> Type) Source # | |
Defined in Data.Store.Impl | |
| (GStorePeek a, GStorePeek b) => GStorePeek (a :*: b) Source # | |
Defined in Data.Store.Impl | |
| (FitsInByte (SumArity (a :+: b)), GStorePeekSum 0 (a :+: b)) => GStorePeek (a :+: b) Source # | |
Defined in Data.Store.Impl | |
| Store a => GStorePeek (K1 i a :: Type -> Type) Source # | |
Defined in Data.Store.Impl | |
| GStorePeek f => GStorePeek (M1 i c f) Source # | |
Defined in Data.Store.Impl | |
Exceptions thrown by Peek
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
| |
Instances
| Exception PeekException | |
Defined in Data.Store.Core Methods toException :: PeekException -> SomeException # fromException :: SomeException -> Maybe PeekException # displayException :: PeekException -> String # backtraceDesired :: PeekException -> Bool # | |
| Show PeekException | |
Defined in Data.Store.Core Methods showsPrec :: Int -> PeekException -> ShowS show :: PeekException -> String showList :: [PeekException] -> ShowS | |
| Eq PeekException | |
Defined in Data.Store.Core | |
peekException :: Text -> Peek a Source #
Throws a PeekException.