git.iko.soy/streamly
on fa9fa09 help sign in
streamly/core/src/Streamly/Data/MutByteArray.hs
90 lines 3.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 for fast binary serialization and
9-- deserialization of Haskell values. Higher level unboxed array modules
10-- "Streamly.Data.Array" and "Streamly.Data.MutArray" are built on top of this
11-- module. This module provides two type classes for serialization, 'Unbox' and
12-- 'Serialize'. The speed is similar to, and in some cases many times faster
13-- than the store package. Conceptually, the 'Serialize' type class works in
14-- the same way as store.
15--
16-- You probably want the higher level
17-- 'Streamly.Internal.Data.Array.pinnedSerialize' and
18-- 'Streamly.Internal.Data.Array.deserialize' from the "Streamly.Data.Array"
19-- module.
20--
21-- == Mutable Byte Array
22--
23-- 'MutByteArray' is a primitive mutable array in the IO monad. 'Unbox' and
24-- 'Serialize' type classes use this primitive array to serialize data to and
25-- deserialize it from. This array is used to build higher level unboxed
26-- array types 'Streamly.Data.MutArray.MutArray' and 'Streamly.Data.Array.Array'.
27--
28-- == Using Unbox
29--
30-- The 'Unbox' type class is simple and used to serialize non-recursive fixed
31-- size data types. This type class is primarily used to implement unboxed
32-- arrays. Unboxed arrays are just a sequence of serialized fixed length
33-- Haskell data types. Instances of this type class can be derived using
34-- 'Generic' or template haskell based deriving functions provided in this
35-- module.
36--
37-- Writing a data type to an array using the array creation routines in
38-- "Streamly.Data.Array" or "Streamly.Data.MutArray" (e.g. @writeN@ or
39-- @fromListN@), serializes the type to the array. Similarly, reading the data
40-- type from the array deserializes it. You can also serialize and deserialize
41-- directly to and from a 'MutByteArray', using the type class methods.
42--
43-- == Using Serialize
44--
45-- The 'Serialize' type class is a superset of the 'Unbox' type class, it can
46-- serialize variable length data types as well e.g. Haskell lists. Use
47-- 'deriveSerialize' to derive the instances of the type class automatically
48-- and then use the type class methods to serialize and deserialize to and from
49-- a 'MutByteArray'.
50--
51-- See 'Streamly.Internal.Data.Array.pinnedSerialize' and
52-- 'Streamly.Internal.Data.Array.deserialize' for 'Array' type based
53-- serialization.
54--
55module Streamly.Data.MutByteArray
56 (
58 -- * Mutable Byte Array
59 -- | The standard way to read from or write to a 'MutByteArray' is by using
60 -- the 'Unbox' or 'Serialize' type class methods.
61 MutByteArray
62 , isPinned
63 , pin
64 , unpin
65 , new
66 , pinnedNew
68 -- * Unbox
69 , Unbox(..)
70 , deriveUnbox
72 -- * Serialize
73 , Serialize(..)
75 -- Deriving Serialize
76 , SerializeConfig
77 , serializeConfig
78 , inlineAddSizeTo
79 , inlineSerializeAt
80 , inlineDeserializeAt
82 , deriveSerialize
83 , deriveSerializeWith
84 ) where
86--------------------------------------------------------------------------------
87-- Imports
88--------------------------------------------------------------------------------
90import Streamly.Internal.Data.MutByteArray