store: Fast binary serialization

[ data, library, mit, serialization ] [ Propose Tags ] [ Report a vulnerability ]

Flags

Manual Flags

NameDescriptionDefault
comparison-benchDisabled
small-benchDisabled
Automatic Flags
NameDescriptionDefault
integer-simple

Use the simple integer library instead of integer-gmp

Disabled

Use -f <flag> to enable a flag, or -f -<flag> to disable that flag. More info

Downloads

Note: This package has metadata revisions in the cabal description newer than included in the tarball. To unpack the package including the revisions, use 'cabal get'.

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

  • No Candidates
Versions [RSS] 0.1.0.0, 0.1.0.1, 0.2.0.0, 0.2.1.0, 0.2.1.1, 0.2.1.2, 0.3, 0.3.1, 0.4.0, 0.4.1, 0.4.2, 0.4.3, 0.4.3.1, 0.4.3.2, 0.5.0, 0.5.0.1, 0.5.1.0, 0.5.1.1, 0.5.1.2, 0.6.0, 0.6.0.1, 0.6.1, 0.7.0, 0.7.1, 0.7.2, 0.7.3, 0.7.4, 0.7.5, 0.7.6, 0.7.7, 0.7.8, 0.7.9, 0.7.10, 0.7.11, 0.7.12, 0.7.13, 0.7.14, 0.7.15, 0.7.16, 0.7.17, 0.7.18, 0.7.19 (info)
Change log ChangeLog.md
Dependencies array (>=0.5.0.0), async (>=2.0.2), base (>=4.7 && <5), base-orphans (>=0.4.3), base64-bytestring (>=0.1.1), bifunctors (>=4.0), bytestring (>=0.10.4.0), containers (>=0.5.5.1), contravariant (>=1.3), cryptohash-sha1 (>=0.11.6), deepseq (>=1.3.0.2), directory (>=1.2), fail (>=4.9), filepath (>=1.3), free (>=4.11), ghc-prim (>=0.3.1.0), hashable (>=1.2.3.1), hspec (>=2.1.2), hspec-smallcheck (>=0.3.0), integer-gmp (>=0.5.1.0), integer-simple (>=0.1.1.1), lifted-base (>=0.2.3.3), monad-control (>=0.3.3.0), mono-traversable (>=0.7.0), nats (>=1), network (>=2.6.0.2), primitive (>=0.6), resourcet (>=1.1.3.3), safe (>=0.3.8), semigroups (>=0.8), smallcheck (>=1.1.1), store-core (>=0.4 && <0.5), syb (>=0.4.4), template-haskell (>=2.9.0.0), text (>=1.2.0.4), th-lift (>=0.7.1), th-lift-instances (>=0.1.4), th-orphans (>=0.13.2), th-reify-many (>=0.1.6), th-utilities (>=0.2), time (>=1.5), transformers (>=0.3.0.0), unordered-containers (>=0.2.5.1), vector (>=0.10.12.3 && <0.13.2.0), void (>=0.5.11) [details]
Tested with ghc ==9.4.5, ghc ==9.2.8, ghc ==9.0.2, ghc ==8.10.7, ghc ==8.8.4, ghc ==8.6.5, ghc ==8.4.4
License MIT
Copyright 2016 FP Complete
Author
Maintainer Michael Sloan <mgsloan@gmail.com>
Revised Revision 1 made by Bodigrim at 2024-11-05T23:53:18Z
Category Serialization, Data
Home page https://github.com/mgsloan/store#readme
Bug tracker https://github.com/mgsloan/store/issues
Source repo head: git clone https://github.com/mgsloan/store
Uploaded by MichaelSloan at 2023-10-06T16:44:25Z
Distributions Arch:0.7.18, Debian:0.7.6, LTSHaskell:0.7.18, NixOS:0.7.18
Reverse Dependencies 27 direct, 50 indirect [details]
Downloads 34126 total (235 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2023-10-06 [all 1 reports]

Readme for store-0.7.18

[back to package description]

store

The 'store' package provides efficient binary serialization. There are a couple features that particularly distinguish it from most prior Haskell serialization libraries:

  • Its primary goal is speed. By default, direct machine representations are used for things like numeric values (Int, Double, Word32, etc) and buffers (Text, ByteString, Vector, etc). This means that much of serialization uses the equivalent of memcpy.

    We have plans for supporting architecture independent serialization - see #36 and #31. This plan makes little endian the default, so that the most common endianness has no overhead.

    • Another way that the serialization behavior can vary is if integer-simple is used instead of GHC's default of using GMP. Integer serialized with the integer-simple flag enabled are not compatible with those serialized without the flag enabled.
  • Instead of implementing lazy serialization / deserialization involving multiple input / output buffers, peek and poke always work with a single buffer. This buffer is allocated by asking the value for its size before encoding. This simplifies the encoding logic, and allows for highly optimized tight loops.

  • store can optimize size computations by knowing when some types always use the same number of bytes. This allows us to compute the byte size of a Vector Int32 by just doing length v * 4.

It also features:

  • Optimized serialization instances for many types from base, vector, bytestring, text, containers, time, template-haskell, and more.

  • TH and GHC Generics based generation of Store instances for datatypes.

  • TH generation of testcases.

  • Utilities for streaming encoding / decoding of Store encoded messages, via 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 Vector will read the vector's length 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 issue #122.

  • Serialization may vary based on the version of datatypes. For example, Text serialized from text < 2 will not be compatible with Text from text >= 2, because the internal representation switched from UTF-16 to UTF-8.

Blog posts