git.iko.soy/streamly
on ba01fcd help sign in
streamly/core/src/Streamly/Data/Array/Unboxed.hs
104 lines 3.5 kB history raw
1#include "inline.hs"
3-- |
4-- Module : Streamly.Data.Array.Unboxed
5-- Copyright : (c) 2019 Composewell Technologies
6--
7-- License : BSD3
8-- Maintainer : streamly@composewell.com
9-- Stability : released
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-- Array creation APIs require a 'MonadIO' Monad, except 'fromList' which is a
28-- pure API. To operate on streams in pure Monads like 'Identity' you can hoist
29-- it to IO monad as follows:
30--
31-- >>> import Data.Functor.Identity (Identity, runIdentity)
32-- >>> s = Stream.fromList [1..10] :: Stream Identity Int
33-- >>> s1 = Stream.hoist (return . runIdentity) s :: Stream IO Int
34-- >>> Stream.fold Array.write s1 :: IO (Array Int)
35-- [1,2,3,4,5,6,7,8,9,10]
36--
37-- 'unsafePerformIO' can be used to get a pure API from IO, as long as you know
38-- it is safe to do so:
39--
40-- >>> import System.IO.Unsafe (unsafePerformIO)
41-- >>> unsafePerformIO $ Stream.fold Array.write s1 :: Array Int
42-- [1,2,3,4,5,6,7,8,9,10]
43--
44-- To apply a transformation to an array use 'read' to unfold the array into a
45-- stream, apply a transformation on the stream and then use 'write' to fold it
46-- back to an array.
47--
48-- This module is designed to be imported qualified:
49--
50-- > import qualified Streamly.Data.Array.Unboxed as Array
51--
52-- For experimental APIs see "Streamly.Internal.Data.Array.Unboxed".
54module Streamly.Data.Array.Unboxed
55 (
56 A.Array
58 -- * Arrays
59 -- ** Construction
60 -- | When performance matters, the fastest way to generate an array is
61 -- 'writeN'. 'IsList' and 'IsString' instances can be
62 -- used to conveniently construct arrays from literal values.
63 -- 'OverloadedLists' extension or 'fromList' can be used to construct an
64 -- array from a list literal. Similarly, 'OverloadedStrings' extension or
65 -- 'fromList' can be used to construct an array from a string literal.
67 -- Pure List APIs
68 , A.fromListN
69 , A.fromList
71 -- Monadic APIs
72 , A.writeN -- drop new
73 , A.write -- full buffer
74 , writeLastN -- drop old (ring buffer)
76 -- ** Elimination
77 -- 'GHC.Exts.toList' from "GHC.Exts" can be used to convert an array to a
78 -- list.
80 , A.toList
81 , A.read
82 , A.readRev
84 -- ** Casting
85 , cast
86 , asBytes
88 -- ** Random Access
89 , A.length
90 -- , (!!)
91 , A.getIndex
92 )
93where
95import Streamly.Internal.Data.Array.Unboxed as A
97-- $setup
98-- >>> :m
99-- >>> :set -XFlexibleContexts
100-- >>> :set -package streamly
101-- >>> import Streamly.Internal.Data.Stream (Stream)
102-- >>> import Streamly.Data.Array.Unboxed (Array)
103-- >>> import qualified Streamly.Internal.Data.Stream as Stream
104-- >>> import qualified Streamly.Data.Array.Unboxed as Array