git.iko.soy/streamly
on dc58c59 help sign in
streamly/core/src/Streamly/Data/Serialize.hs
79 lines 2.7 kB history raw
1-- |
2-- Module : Streamly.Data.Serialize
3-- Copyright : (c) 2023 Composewell Technologies
4-- License : BSD3-3-Clause
5-- Maintainer : streamly@composewell.com
6-- Portability : GHC
7--
8-- Fast binary serialization and deserialization of Haskell values to and from
9-- arrays. This module provides two type classes for serialization, 'Unbox' and
10-- 'Serialize'. The speed is similar to, and in some cases many times faster
11-- than the store package. Conceptually, the 'Serialize' type class works in
12-- the same way as store.
13--
14-- == Using Unbox
15--
16-- The 'Unbox' type class is simple and used to serialize non-recursive fixed
17-- size data types. This type class is primarily used to implement unboxed
18-- arrays. Unboxed arrays are just serialization of fixed length Haskell data
19-- types. Instances of this type class can be derived using 'Generic' or
20-- template haskell based deriving functions provided in this module. Read the
21-- type class documentation for more details.
22--
23-- Writing a data type to an array using the array creation routines in
24-- "Streamly.Data.Array" or "Streamly.Data.MutArray", serializes the type to
25-- the array. Similarly, reading the data type from the array deserializes it.
26--
27-- There are no encode/decode routines provided to serialize or deserialize
28-- using this type class but you can write those easily. Just create a mutable
29-- byte array and use 'pokeByteIndex' to serialize a type, and use
30-- 'peekByteIndex' to deserialize it.
31--
32-- == Using Serialize
33--
34-- The 'Serialize' type class is a superset of the 'Unbox' type class, it can
35-- serialize variable length data types as well e.g. Haskell lists. Use
36-- 'deriveSerialize' to derive the instances of the type class automatically
37-- and then use 'pinnedEncode', 'decode' to serialize and deserialize the type
38-- respectively. You can also create the array yourself and use the type class
39-- functions directly.
40--
41module Streamly.Data.Serialize
42 (
44 -- * MutableByteArray
45 MutByteArray
46 , isPinned
47 , pin
48 , unpin
49 , newByteArray
50 , pinnedNewByteArray
52 -- * Unbox
53 , Unbox(..)
54 , deriveUnbox
56 -- * Serialize
57 , Serialize(..)
59 -- Deriving instances
60 , SerializeConfig
61 , serializeConfig
62 , inlineSize
63 , inlineSerialize
64 , inlineDeserialize
66 , deriveSerialize
67 , deriveSerializeWith
69 -- Encoding and Decoding
70 -- , encode
71 , pinnedEncode
72 , decode
73 ) where
75--------------------------------------------------------------------------------
76-- Imports
77--------------------------------------------------------------------------------
79import Streamly.Internal.Data.Serialize