Streamly.Data.Array.Foreign

This module provides immutable arrays in pinned memory (non GC memory) suitable for long lived data storage, random access and for interfacing with the operating system.

Arrays in this module are chunks of pinned memory that hold a sequence of Storable values of a given type, they cannot store non-serializable data like functions. Once created an array cannot be modified. Pinned memory allows efficient buffering of long lived data without adding any impact to GC. One array is just one pointer visible to GC and it does not have to be copied across generations. Moreover, pinned memory allows communication with foreign consumers and producers (e.g. file or network IO) without copying the data.

Programmer Notes

To apply a transformation to an array use read to unfold the array into a stream, apply a transformation on the stream and then use write to fold it back to an array.

This module is designed to be imported qualified:

import qualified Streamly.Data.Array.Foreign as Array

For experimental APIs see Streamly.Internal.Data.Array.Foreign.

Documentation

data Array a

Instances

a ~ Char => IsString (Array a)

Defined in Streamly.Internal.Data.Array.Foreign.Type

Methods

fromString :: String -> Array a

Storable a => Monoid (Array a)

Defined in Streamly.Internal.Data.Array.Foreign.Type

Methods

mempty :: Array a

mappend :: Array a -> Array a -> Array a

mconcat :: [Array a] -> Array a

Storable a => Semigroup (Array a)

Defined in Streamly.Internal.Data.Array.Foreign.Type

Methods

(<>) :: Array a -> Array a -> Array a

sconcat :: NonEmpty (Array a) -> Array a

stimes :: Integral b => b -> Array a -> Array a

Storable a => IsList (Array a)

Defined in Streamly.Internal.Data.Array.Foreign.Type

Associated Types

type Item (Array a)

Methods

fromList :: [Item (Array a)] -> Array a

fromListN :: Int -> [Item (Array a)] -> Array a

toList :: Array a -> [Item (Array a)]

(Storable a, Read a, Show a) => Read (Array a)

Defined in Streamly.Internal.Data.Array.Foreign.Type

Methods

readsPrec :: Int -> ReadS (Array a)

readList :: ReadS [Array a]

readPrec :: ReadPrec (Array a)

readListPrec :: ReadPrec [Array a]

(Show a, Storable a) => Show (Array a)

Defined in Streamly.Internal.Data.Array.Foreign.Type

Methods

showsPrec :: Int -> Array a -> ShowS

show :: Array a -> String

showList :: [Array a] -> ShowS

NFData (Array a)

Defined in Streamly.Internal.Data.Array.Foreign.Type

Methods

rnf :: Array a -> ()

(Storable a, Eq a) => Eq (Array a)

Defined in Streamly.Internal.Data.Array.Foreign.Type

Methods

(==) :: Array a -> Array a -> Bool

(/=) :: Array a -> Array a -> Bool

(Storable a, Ord a) => Ord (Array a)

Defined in Streamly.Internal.Data.Array.Foreign.Type

Methods

compare :: Array a -> Array a -> Ordering

(<) :: Array a -> Array a -> Bool

(<=) :: Array a -> Array a -> Bool

(>) :: Array a -> Array a -> Bool

(>=) :: Array a -> Array a -> Bool

max :: Array a -> Array a -> Array a

min :: Array a -> Array a -> Array a

type Item (Array a)

Defined in Streamly.Internal.Data.Array.Foreign.Type

type Item (Array a) = a

Arrays

Construction

When performance matters, the fastest way to generate an array is writeN. IsList and IsString instances can be used to conveniently construct arrays from literal values. OverloadedLists extension or fromList can be used to construct an array from a list literal. Similarly, OverloadedStrings extension or fromList can be used to construct an array from a string literal.

fromListN :: Storable a => Int -> [a] -> Array a

Create an Array from the first N elements of a list. The array is allocated to size N, if the list terminates before N elements then the array may hold less than N elements.

Since 0.7.0 (Streamly.Memory.Array)

Since: 0.8.0

fromList :: Storable a => [a] -> Array a

Create an Array from a list. The list must be of finite size.

Since 0.7.0 (Streamly.Memory.Array)

Since: 0.8.0

writeN :: forall m a. (MonadIO m, Storable a) => Int -> Fold m a (Array a)

writeN n folds a maximum of n elements from the input stream to an Array.

Since 0.7.0 (Streamly.Memory.Array)

Since: 0.8.0

write :: forall m a. (MonadIO m, Storable a) => Fold m a (Array a)

Fold the whole input to a single array.

Caution! Do not use this on infinite streams.

Since 0.7.0 (Streamly.Memory.Array)

Since: 0.8.0

writeLastN :: (Storable a, MonadIO m) => Int -> Fold m a (Array a)

writeLastN n folds a maximum of n elements from the end of the input stream to an Array.

Since: 0.8.0

Elimination

toList :: Storable a => Array a -> [a]

Convert an Array into a list.

Since 0.7.0 (Streamly.Memory.Array)

Since: 0.8.0

read :: forall m a. (Monad m, Storable a) => Unfold m (Array a) a

Unfold an array into a stream.

Since 0.7.0 (Streamly.Memory.Array)

Since: 0.8.0

readRev :: forall m a. (Monad m, Storable a) => Unfold m (Array a) a

Unfold an array into a stream in reverse order.

Since: 0.8.0

Casting

cast :: forall a b. Storable b => Array a -> Maybe (Array b)

Cast an array having elements of type a into an array having elements of type b. The length of the array should be a multiple of the size of the target element otherwise Nothing is returned.

Since: 0.8.0

asBytes :: Array a -> Array Word8

Cast an Array a into an Array Word8.

Since: 0.8.0

Random Access

length :: forall a. Storable a => Array a -> Int

O(1) Get the length of the array i.e. the number of elements in the array.

Since 0.7.0 (Streamly.Memory.Array)

Since: 0.8.0

getIndex :: forall a. Storable a => Array a -> Int -> Maybe a

O(1) Lookup the element at the given index. Index starts from 0.

Since: 0.8.0