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