Copyright | (c) Dan Doel 2016 |
---|---|
License | BSD-style |
Maintainer | Libraries <libraries@haskell.org> |
Portability | non-portable |
Safe Haskell | None |
Language | Haskell2010 |
GHC contains three general classes of value types:
- Unboxed types: values are machine values made up of fixed numbers of bytes
- Unlifted types: values are pointers, but strictly evaluated
- 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.
- data UnliftedArray e = UnliftedArray ArrayArray#
- data MutableUnliftedArray s e = MutableUnliftedArray (MutableArrayArray# s)
- class PrimUnlifted a where
- unsafeNewUnliftedArray :: PrimMonad m => Int -> m (MutableUnliftedArray (PrimState m) a)
- newUnliftedArray :: (PrimMonad m, PrimUnlifted a) => Int -> a -> m (MutableUnliftedArray (PrimState m) a)
- setUnliftedArray :: (PrimMonad m, PrimUnlifted a) => MutableUnliftedArray (PrimState m) a -> a -> m ()
- sizeofUnliftedArray :: UnliftedArray e -> Int
- sizeofMutableUnliftedArray :: MutableUnliftedArray s e -> Int
- readUnliftedArray :: (PrimMonad m, PrimUnlifted a) => MutableUnliftedArray (PrimState m) a -> Int -> m a
- writeUnliftedArray :: (PrimMonad m, PrimUnlifted a) => MutableUnliftedArray (PrimState m) a -> Int -> a -> m ()
- indexUnliftedArray :: PrimUnlifted a => UnliftedArray a -> Int -> a
- indexUnliftedArrayM :: (PrimUnlifted a, Monad m) => UnliftedArray a -> Int -> m a
- unsafeFreezeUnliftedArray :: PrimMonad m => MutableUnliftedArray (PrimState m) a -> m (UnliftedArray a)
- freezeUnliftedArray :: PrimMonad m => MutableUnliftedArray (PrimState m) a -> Int -> Int -> m (UnliftedArray a)
- thawUnliftedArray :: PrimMonad m => UnliftedArray a -> Int -> Int -> m (MutableUnliftedArray (PrimState m) a)
- runUnliftedArray :: (forall s. ST s (MutableUnliftedArray s a)) -> UnliftedArray a
- sameMutableUnliftedArray :: MutableUnliftedArray s a -> MutableUnliftedArray s a -> Bool
- copyUnliftedArray :: PrimMonad m => MutableUnliftedArray (PrimState m) a -> Int -> UnliftedArray a -> Int -> Int -> m ()
- copyMutableUnliftedArray :: PrimMonad m => MutableUnliftedArray (PrimState m) a -> Int -> MutableUnliftedArray (PrimState m) a -> Int -> Int -> m ()
- cloneUnliftedArray :: UnliftedArray a -> Int -> Int -> UnliftedArray a
- cloneMutableUnliftedArray :: PrimMonad m => MutableUnliftedArray (PrimState m) a -> Int -> Int -> m (MutableUnliftedArray (PrimState m) a)
- unliftedArrayToList :: PrimUnlifted a => UnliftedArray a -> [a]
- unliftedArrayFromList :: PrimUnlifted a => [a] -> UnliftedArray a
- unliftedArrayFromListN :: forall a. PrimUnlifted a => Int -> [a] -> UnliftedArray a
- foldrUnliftedArray :: forall a b. PrimUnlifted a => (a -> b -> b) -> b -> UnliftedArray a -> b
- foldrUnliftedArray' :: forall a b. PrimUnlifted a => (a -> b -> b) -> b -> UnliftedArray a -> b
- foldlUnliftedArray :: forall a b. PrimUnlifted a => (b -> a -> b) -> b -> UnliftedArray a -> b
- foldlUnliftedArray' :: forall a b. PrimUnlifted a => (b -> a -> b) -> b -> UnliftedArray a -> b
- mapUnliftedArray :: (PrimUnlifted a, PrimUnlifted b) => (a -> b) -> UnliftedArray a -> UnliftedArray b
Types
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.
PrimUnlifted a => IsList (UnliftedArray a) Source # | Since: 0.6.4.0 |
(Eq a, PrimUnlifted a) => Eq (UnliftedArray a) Source # | |
(Ord a, PrimUnlifted a) => Ord (UnliftedArray a) Source # | Lexicographic ordering. Subject to change between major versions. Since: 0.6.4.0 |
(Show a, PrimUnlifted a) => Show (UnliftedArray a) Source # | Since: 0.6.4.0 |
PrimUnlifted a => Semigroup (UnliftedArray a) Source # | Since: 0.6.4.0 |
PrimUnlifted a => Monoid (UnliftedArray a) Source # | Since: 0.6.4.0 |
PrimUnlifted (UnliftedArray e) Source # | |
type Item (UnliftedArray a) Source # | |
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.
Eq (MutableUnliftedArray s a) Source # | |
PrimUnlifted (MutableUnliftedArray s e) Source # | |
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#
.
toArrayArray# :: a -> ArrayArray# Source #
fromArrayArray# :: ArrayArray# -> a Source #
PrimUnlifted ThreadId Source # | Since: 0.6.4.0 |
PrimUnlifted ByteArray Source # | |
PrimUnlifted (StablePtr a) Source # | Since: 0.6.4.0 |
PrimUnlifted (TVar a) Source # | Since: 0.6.4.0 |
PrimUnlifted (Weak a) Source # | Since: 0.6.4.0 |
PrimUnlifted (MVar a) Source # | Since: 0.6.4.0 |
PrimUnlifted (Array a) Source # | |
PrimUnlifted (SmallArray a) Source # | |
PrimUnlifted (MutableByteArray s) Source # | |
PrimUnlifted (PrimArray a) Source # | Since: 0.6.4.0 |
PrimUnlifted (UnliftedArray e) Source # | |
PrimUnlifted (MutableArray s a) Source # | |
PrimUnlifted (MutVar s a) Source # | |
PrimUnlifted (SmallMutableArray s a) Source # | |
PrimUnlifted (MutablePrimArray s a) Source # | Since: 0.6.4.0 |
PrimUnlifted (MutableUnliftedArray s e) Source # | |
Operations
unsafeNewUnliftedArray Source #
:: PrimMonad m | |
=> Int | size |
-> m (MutableUnliftedArray (PrimState m) a) |
Creates a new MutableUnliftedArray
. This function is unsafe because it
initializes all elements of the array as pointers to the array itself. Attempting
to read one of these elements before writing to it is in effect an unsafe
coercion from the MutableUnliftedArray s a
to the element type.
:: (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.
:: (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
.
sizeofMutableUnliftedArray :: MutableUnliftedArray s e -> Int Source #
Yields the length of a MutableUnliftedArray
.
:: (PrimMonad m, PrimUnlifted a) | |
=> MutableUnliftedArray (PrimState m) a | source |
-> Int | index |
-> m a |
Gets the value at the specified position of a MutableUnliftedArray
.
:: (PrimMonad m, PrimUnlifted a) | |
=> MutableUnliftedArray (PrimState m) a | destination |
-> Int | index |
-> a | value |
-> m () |
Sets the value at the specified position of a MutableUnliftedArray
.
:: PrimUnlifted a | |
=> UnliftedArray a | source |
-> Int | index |
-> a |
Gets the value at the specified position of an UnliftedArray
.
:: (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.
:: 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.
:: 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.
runUnliftedArray :: (forall s. ST s (MutableUnliftedArray s a)) -> UnliftedArray a Source #
Execute a stateful computation and freeze the resulting 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.
:: 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 #
:: 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.
:: UnliftedArray a | source |
-> Int | offset |
-> Int | length |
-> UnliftedArray a |
Creates a copy of a portion of an UnliftedArray
cloneMutableUnliftedArray Source #
:: 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.
List Conversion
unliftedArrayToList :: PrimUnlifted a => UnliftedArray a -> [a] Source #
Convert the unlifted array to a list.
unliftedArrayFromList :: PrimUnlifted a => [a] -> UnliftedArray a Source #
unliftedArrayFromListN :: forall a. PrimUnlifted a => Int -> [a] -> UnliftedArray a Source #
Folding
foldrUnliftedArray :: forall a b. PrimUnlifted a => (a -> b -> b) -> b -> UnliftedArray a -> b Source #
Lazy right-associated fold over the elements of an UnliftedArray
.
foldrUnliftedArray' :: forall a b. PrimUnlifted a => (a -> b -> b) -> b -> UnliftedArray a -> b Source #
Strict right-associated fold over the elements of an 'UnliftedArray.
foldlUnliftedArray :: forall a b. PrimUnlifted a => (b -> a -> b) -> b -> UnliftedArray a -> b Source #
Lazy left-associated fold over the elements of an UnliftedArray
.
foldlUnliftedArray' :: forall a b. PrimUnlifted a => (b -> a -> b) -> b -> UnliftedArray a -> b Source #
Strict left-associated fold over the elements of an UnliftedArray
.
Mapping
mapUnliftedArray :: (PrimUnlifted a, PrimUnlifted b) => (a -> b) -> UnliftedArray a -> UnliftedArray b Source #
Map over the elements of an UnliftedArray
.