git.iko.soy/streamly
on master help sign in
streamly/core/src/Streamly/Data/MutByteArray.hs
106 lines 4.3 kB history raw
1-- |
2-- Module : Streamly.Data.MutByteArray
3-- Copyright : (c) 2023 Composewell Technologies
4-- License : BSD3-3-Clause
5-- Maintainer : streamly@composewell.com
6-- Portability : GHC
7--
8-- A low level byte Array type 'MutByteArray', along with type classes 'Unbox'
9-- and 'Serialize' for fast binary serialization and deserialization of Haskell
10-- values. Serialization, deserialization performance is similar to, and in
11-- some cases many times better than the store package. Conceptually, the
12-- 'Serialize' type class works in the same way as store.
13--
14-- Serialize instances are configurable to use constructor names (see
15-- 'Streamly.Internal.Data.MutByteArray.encodeConstrNames'), record field names (see
16-- 'Streamly.Internal.Data.MutByteArray.encodeRecordFields') instead of binary
17-- encoded values. This is an experimental feature which allows JSON like
18-- properties with faster speed. For example, you can change the order of
19-- constructors or record fields without affecting serialized value.
20--
21-- Higher level unboxed array modules "Streamly.Data.Array" and
22-- "Streamly.Data.MutArray" are built on top of this module. Unboxed arrays are
23-- essentially serialized Haskell values. Array modules provide higher level
24-- serialization routines like 'Streamly.Internal.Data.Array.pinnedSerialize'
25-- and 'Streamly.Internal.Data.Array.deserialize' from the
26-- "Streamly.Internal.Data.Array" module.
27--
28-- == Mutable Byte Array
29--
30-- 'MutByteArray' is a primitive mutable array in the IO monad. 'Unbox' and
31-- 'Serialize' type classes use this primitive array to serialize data to and
32-- deserialize it from. This array is used to build higher level unboxed
33-- array types 'Streamly.Data.MutArray.MutArray' and 'Streamly.Data.Array.Array'.
34--
35-- == Using Unbox
36--
37-- The 'Unbox' type class is simple and used to serialize non-recursive fixed
38-- size data types. This type class is primarily used to implement unboxed
39-- arrays. Unboxed arrays are just a sequence of serialized fixed length
40-- Haskell data types. Instances of this type class can be derived using
41-- 'Generic' or template haskell based deriving functions provided in this
42-- module.
43--
44-- Writing a data type to an array using the array creation routines in
45-- "Streamly.Data.Array" or "Streamly.Data.MutArray" (e.g. @writeN@ or
46-- @fromListN@), serializes the type to the array. Similarly, reading the data
47-- type from the array deserializes it. You can also serialize and deserialize
48-- directly to and from a 'MutByteArray', using the type class methods.
49--
50-- == Using Serialize
51--
52-- The 'Serialize' type class is a superset of the 'Unbox' type class, it can
53-- serialize variable length data types as well e.g. Haskell lists. Use
54-- 'deriveSerialize' to derive the instances of the type class automatically
55-- and then use the type class methods to serialize and deserialize to and from
56-- a 'MutByteArray'.
57--
58-- See 'Streamly.Internal.Data.Array.pinnedSerialize' and
59-- 'Streamly.Internal.Data.Array.deserialize' for 'Array' type based
60-- serialization.
61--
62-- == Comparing serialized values
63--
64-- When using the `Unbox` type class the same value may result in differing
65-- serialized bytes because of unused uninitialized data in case of sum types.
66-- Therefore, byte comparison of serialized values is not reliable.
67--
68-- However, the 'Serialize' type class guarantees that the serialized values
69-- are always exactly the same and byte comparison of serialized is reliable.
70--
71module Streamly.Data.MutByteArray
72 (
74 -- * Mutable Byte Array
75 -- | The standard way to read from or write to a 'MutByteArray' is by using
76 -- the 'Unbox' or 'Serialize' type class methods.
77 MutByteArray
78 , isPinned
79 , pin
80 , unpin
81 , new
82 , pinnedNew
84 -- * Unbox
85 , Unbox(..)
86 , deriveUnbox
88 -- * Serialize
89 , Serialize(..)
91 -- ** Instance Config
92 , SerializeConfig
93 , inlineAddSizeTo
94 , inlineSerializeAt
95 , inlineDeserializeAt
97 -- ** Instance Deriving
98 , deriveSerialize
99 , deriveSerializeWith
100 ) where
102--------------------------------------------------------------------------------
103-- Imports
104--------------------------------------------------------------------------------
106import Streamly.Internal.Data.MutByteArray