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