primitive-0.6.3.0: Primitive memory-related operations

Copyright(c) Dan Doel 2016
LicenseBSD-style
MaintainerLibraries <libraries@haskell.org>
Portabilitynon-portable
Safe HaskellNone
LanguageHaskell2010

Data.Primitive.UnliftedArray

Description

GHC contains three general classes of value types:

  1. Unboxed types: values are machine values made up of fixed numbers of bytes
  2. Unlifted types: values are pointers, but strictly evaluated
  3. Lifted types: values are pointers, lazily evaluated

The first category can be stored in a ByteArray, and this allows types in category 3 that are simple wrappers around category 1 types to be stored more efficiently using a ByteArray. This module provides the same facility for category 2 types.

GHC has two primitive types, ArrayArray# and MutableArrayArray#. These are arrays of pointers, but of category 2 values, so they are known to not be bottom. This allows types that are wrappers around such types to be stored in an array without an extra level of indirection.

The way that the ArrayArray# API works is that one can read and write ArrayArray# values to the positions. This works because all category 2 types share a uniform representation, unlike unboxed values which are represented by varying (by type) numbers of bytes. However, using the this makes the internal API very unsafe to use, as one has to coerce values to and from ArrayArray#.

The API presented by this module is more type safe. UnliftedArray and MutableUnliftedArray are parameterized by the type of arrays they contain, and the coercions necessary are abstracted into a class, PrimUnlifted, of things that are eligible to be stored.

Synopsis

Documentation

data UnliftedArray e Source #

Immutable arrays that efficiently store types that are simple wrappers around unlifted primitive types. The values of the unlifted type are stored directly, eliminating a layer of indirection.

data MutableUnliftedArray s e Source #

Mutable arrays that efficiently store types that are simple wrappers around unlifted primitive types. The values of the unlifted type are stored directly, eliminating a layer of indirection.

class PrimUnlifted a where Source #

Classifies the types that are able to be stored in UnliftedArray and MutableUnliftedArray. These should be types that are just liftings of the unlifted pointer types, so that their internal contents can be safely coerced into an ArrayArray#.

Minimal complete definition

toArrayArray#, fromArrayArray#

unsafeNewUnliftedArray Source #

Arguments

:: PrimMonad m 
=> Int

size

-> m (MutableUnliftedArray (PrimState m) a) 

Creates a new MutableUnliftedArray. This function is unsafe, because it allows access to the raw contents of the underlying ArrayArray#.

newUnliftedArray Source #

Arguments

:: (PrimMonad m, PrimUnlifted a) 
=> Int

size

-> a

initial value

-> m (MutableUnliftedArray (PrimState m) a) 

Creates a new MutableUnliftedArray with the specified value as initial contents. This is slower than unsafeNewUnliftedArray, but safer.

setUnliftedArray Source #

Arguments

:: (PrimMonad m, PrimUnlifted a) 
=> MutableUnliftedArray (PrimState m) a

destination

-> a

value to fill with

-> m () 

Sets all the positions in an unlifted array to the designated value.

sizeofUnliftedArray :: UnliftedArray e -> Int Source #

Yields the length of an UnliftedArray.

readUnliftedArray Source #

Arguments

:: (PrimMonad m, PrimUnlifted a) 
=> MutableUnliftedArray (PrimState m) a

source

-> Int

index

-> m a 

Gets the value at the specified position of a MutableUnliftedArray.

writeUnliftedArray Source #

Arguments

:: (PrimMonad m, PrimUnlifted a) 
=> MutableUnliftedArray (PrimState m) a

destination

-> Int

index

-> a

value

-> m () 

Sets the value at the specified position of a MutableUnliftedArray.

indexUnliftedArray Source #

Arguments

:: PrimUnlifted a 
=> UnliftedArray a

source

-> Int

index

-> a 

Gets the value at the specified position of an UnliftedArray.

indexUnliftedArrayM Source #

Arguments

:: (PrimUnlifted a, Monad m) 
=> UnliftedArray a

source

-> Int

index

-> m a 

Gets the value at the specified position of an UnliftedArray. The purpose of the Monad is to allow for being eager in the UnliftedArray value without having to introduce a data dependency directly on the result value.

It should be noted that this is not as much of a problem as with a normal Array, because elements of an UnliftedArray are guaranteed to not be exceptional. This function is provided in case it is more desirable than being strict in the result value.

unsafeFreezeUnliftedArray :: PrimMonad m => MutableUnliftedArray (PrimState m) a -> m (UnliftedArray a) Source #

Freezes a MutableUnliftedArray, yielding an UnliftedArray. This simply marks the array as frozen in place, so it should only be used when no further modifications to the mutable array will be performed.

freezeUnliftedArray Source #

Arguments

:: PrimMonad m 
=> MutableUnliftedArray (PrimState m) a

source

-> Int

offset

-> Int

length

-> m (UnliftedArray a) 

Freezes a portion of a MutableUnliftedArray, yielding an UnliftedArray. This operation is safe, in that it copies the frozen portion, and the existing mutable array may still be used afterward.

thawUnliftedArray Source #

Arguments

:: PrimMonad m 
=> UnliftedArray a

source

-> Int

offset

-> Int

length

-> m (MutableUnliftedArray (PrimState m) a) 

Thaws a portion of an UnliftedArray, yielding a MutableUnliftedArray. This copies the thawed portion, so mutations will not affect the original array.

sameMutableUnliftedArray :: MutableUnliftedArray s a -> MutableUnliftedArray s a -> Bool Source #

Determines whether two MutableUnliftedArray values are the same. This is object/pointer identity, not based on the contents.

copyUnliftedArray Source #

Arguments

:: PrimMonad m 
=> MutableUnliftedArray (PrimState m) a

destination

-> Int

offset into destination

-> UnliftedArray a

source

-> Int

offset into source

-> Int

number of elements to copy

-> m () 

Copies the contents of an immutable array into a mutable array.

copyMutableUnliftedArray Source #

Arguments

:: PrimMonad m 
=> MutableUnliftedArray (PrimState m) a

destination

-> Int

offset into destination

-> MutableUnliftedArray (PrimState m) a

source

-> Int

offset into source

-> Int

number of elements to copy

-> m () 

Copies the contents of one mutable array into another.

cloneUnliftedArray Source #

Arguments

:: UnliftedArray a

source

-> Int

offset

-> Int

length

-> UnliftedArray a 

Creates a copy of a portion of an UnliftedArray

cloneMutableUnliftedArray Source #

Arguments

:: PrimMonad m 
=> MutableUnliftedArray (PrimState m) a

source

-> Int

offset

-> Int

length

-> m (MutableUnliftedArray (PrimState m) a) 

Creates a new MutableUnliftedArray containing a copy of a portion of another mutable array.