git.iko.soy/streamly
on 1e51921 help sign in
streamly/src/Streamly/Memory/Array.hs
73 lines 2.3 kB history raw
1#include "inline.hs"
3-- |
4-- Module : Streamly.Memory.Array
5-- Copyright : (c) 2019 Composewell Technologies
6--
7-- License : BSD3
8-- Maintainer : streamly@composewell.com
9-- Stability : experimental
10-- Portability : GHC
11--
12-- This module provides immutable arrays in pinned memory (non GC memory)
13-- suitable for long lived data storage, random access and for interfacing with
14-- the operating system.
15--
16-- Arrays in this module are chunks of pinned memory that hold a sequence of
17-- 'Storable' values of a given type, they cannot store non-serializable data
18-- like functions. Once created an array cannot be modified. Pinned memory
19-- allows efficient buffering of long lived data without adding any impact to
20-- GC. One array is just one pointer visible to GC and it does not have to be
21-- copied across generations. Moreover, pinned memory allows communication
22-- with foreign consumers and producers (e.g. file or network IO) without
23-- copying the data.
24--
25-- = Programmer Notes
26--
27-- To apply a transformation to an array use 'read' to unfold the array into a
28-- stream, apply a transformation on the stream and then use 'write' to fold it
29-- back to an array.
30--
31-- This module is designed to be imported qualified:
32--
33-- > import qualified Streamly.Array as A
34--
35-- For experimental APIs see "Streamly.Internal.Memory.Array".
37module Streamly.Memory.Array
38 (
39 A.Array
41 -- * Arrays
42 -- ** Construction
43 -- | When performance matters, the fastest way to generate an array is
44 -- 'writeN'. 'IsList' and 'IsString' instances can be
45 -- used to conveniently construct arrays from literal values.
46 -- 'OverloadedLists' extension or 'fromList' can be used to construct an
47 -- array from a list literal. Similarly, 'OverloadedStrings' extension or
48 -- 'fromList' can be used to construct an array from a string literal.
50 -- Pure List APIs
51 , A.fromListN
52 , A.fromList
54 -- Monadic APIs
55 , A.writeN -- drop new
56 , A.write -- full buffer
57 -- , writeLastN -- drop old (ring buffer)
59 -- ** Elimination
60 -- 'GHC.Exts.toList' from "GHC.Exts" can be used to convert an array to a
61 -- list.
63 , A.toList
64 , A.read
66 -- ** Random Access
67 , A.length
68 -- , (!!)
69 -- , A.readIndex
70 )
71where
73import Streamly.Internal.Memory.Array as A