git.iko.soy/streamly
on e856425 help sign in
streamly/src/Streamly/Memory/Array.hs
74 lines 2.4 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.Data.Array.Unboxed".
37module Streamly.Memory.Array
38 {-# DEPRECATED "Use Streamly.Data.Array.Foreign instead" #-}
39 (
40 A.Array
42 -- * Arrays
43 -- ** Construction
44 -- | When performance matters, the fastest way to generate an array is
45 -- 'writeN'. 'IsList' and 'IsString' instances can be
46 -- used to conveniently construct arrays from literal values.
47 -- 'OverloadedLists' extension or 'fromList' can be used to construct an
48 -- array from a list literal. Similarly, 'OverloadedStrings' extension or
49 -- 'fromList' can be used to construct an array from a string literal.
51 -- Pure List APIs
52 , A.fromListN
53 , A.fromList
55 -- Monadic APIs
56 , A.writeN -- drop new
57 , A.write -- full buffer
58 -- , writeLastN -- drop old (ring buffer)
60 -- ** Elimination
61 -- 'GHC.Exts.toList' from "GHC.Exts" can be used to convert an array to a
62 -- list.
64 , A.toList
65 , A.read
67 -- ** Random Access
68 , A.length
69 -- , (!!)
70 -- , A.readIndex
71 )
72where
74import Streamly.Internal.Data.Array.Unboxed as A