git.iko.soy/streamly
on bd33fc7 help sign in
streamly/src/Streamly/Memory/Array.hs
80 lines 2.5 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 be
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 -- * Arrays
49 -- ** Construction
50 -- | When performance matters, the fastest way to generate an array is
51 -- 'writeN'. 'IsList' and 'IsString' instances can be
52 -- used to conveniently construct arrays from literal values.
53 -- 'OverloadedLists' extension or 'fromList' can be used to construct an
54 -- array from a list literal. Similarly, 'OverloadedStrings' extension or
55 -- 'fromList' can be used to construct an array from a string literal.
57 -- Pure List APIs
58 , A.fromListN
59 , A.fromList
61 -- Monadic APIs
62 , A.writeN -- drop new
63 , A.write -- full buffer
64 -- , writeLastN -- drop old (ring buffer)
66 -- ** Elimination
67 -- 'GHC.Exts.toList' from "GHC.Exts" can be used to convert an array to a
68 -- list.
70 , A.toList
71 , A.read
73 -- ** Random Access
74 , A.length
75 -- , (!!)
76 -- , A.readIndex
77 )
78where
80import Streamly.Internal.Memory.Array as A