-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Primitive memory-related operations
--
-- This package provides various primitive memory-related operations.
@package primitive
@version 0.9.1.0
-- | Machine-dependent constants.
module Data.Primitive.MachDeps
sIZEOF_CHAR :: Int
aLIGNMENT_CHAR :: Int
sIZEOF_INT :: Int
aLIGNMENT_INT :: Int
sIZEOF_WORD :: Int
aLIGNMENT_WORD :: Int
sIZEOF_DOUBLE :: Int
aLIGNMENT_DOUBLE :: Int
sIZEOF_FLOAT :: Int
aLIGNMENT_FLOAT :: Int
sIZEOF_PTR :: Int
aLIGNMENT_PTR :: Int
sIZEOF_FUNPTR :: Int
aLIGNMENT_FUNPTR :: Int
sIZEOF_STABLEPTR :: Int
aLIGNMENT_STABLEPTR :: Int
sIZEOF_INT8 :: Int
aLIGNMENT_INT8 :: Int
sIZEOF_WORD8 :: Int
aLIGNMENT_WORD8 :: Int
sIZEOF_INT16 :: Int
aLIGNMENT_INT16 :: Int
sIZEOF_WORD16 :: Int
aLIGNMENT_WORD16 :: Int
sIZEOF_INT32 :: Int
aLIGNMENT_INT32 :: Int
sIZEOF_WORD32 :: Int
aLIGNMENT_WORD32 :: Int
sIZEOF_INT64 :: Int
aLIGNMENT_INT64 :: Int
sIZEOF_WORD64 :: Int
aLIGNMENT_WORD64 :: Int
type Word64_# = Word64#
type Int64_# = Int64#
-- | Primitive state-transformer monads.
module Control.Monad.Primitive
-- | Class of monads which can perform primitive state-transformer actions.
class Monad m => PrimMonad (m :: Type -> Type) where {
-- | State token type.
type PrimState (m :: Type -> Type);
}
-- | Execute a primitive operation.
primitive :: PrimMonad m => (State# (PrimState m) -> (# State# (PrimState m), a #)) -> m a
-- | RealWorld is deeply magical. It is primitive, but it is
-- not unlifted (hence ptrArg). We never manipulate
-- values of type RealWorld; it's only used in the type system, to
-- parameterise State#.
data RealWorld
-- | Execute a primitive operation with no result.
primitive_ :: PrimMonad m => (State# (PrimState m) -> State# (PrimState m)) -> m ()
-- | Class of primitive monads for state-transformer actions.
--
-- Unlike PrimMonad, this typeclass requires that the
-- Monad be fully expressed as a state transformer, therefore
-- disallowing other monad transformers on top of the base IO or
-- ST.
class PrimMonad m => PrimBase (m :: Type -> Type)
-- | Expose the internal structure of the monad.
internal :: PrimBase m => m a -> State# (PrimState m) -> (# State# (PrimState m), a #)
-- | PrimMonad's state token type can be annoying to handle in
-- constraints. This typeclass lets users (visually) notice
-- PrimState equality constraints less, by witnessing that s ~
-- PrimState m.
class (PrimMonad m, s ~ PrimState m) => MonadPrim s (m :: Type -> Type)
-- | PrimBase's state token type can be annoying to handle in
-- constraints. This typeclass lets users (visually) notice
-- PrimState equality constraints less, by witnessing that s ~
-- PrimState m.
class (PrimBase m, MonadPrim s m) => MonadPrimBase s (m :: Type -> Type)
-- | Lifts a PrimBase into another PrimMonad with the same
-- underlying state token type.
liftPrim :: (PrimBase m1, PrimMonad m2, PrimState m1 ~ PrimState m2) => m1 a -> m2 a
-- | Convert a PrimBase to another monad with the same state token.
primToPrim :: (PrimBase m1, PrimMonad m2, PrimState m1 ~ PrimState m2) => m1 a -> m2 a
-- | Convert a PrimBase with a RealWorld state token to
-- IO
primToIO :: (PrimBase m, PrimState m ~ RealWorld) => m a -> IO a
-- | Convert a PrimBase to ST
primToST :: PrimBase m => m a -> ST (PrimState m) a
-- | Convert an IO action to a PrimMonad.
ioToPrim :: (PrimMonad m, PrimState m ~ RealWorld) => IO a -> m a
-- | Convert an ST action to a PrimMonad.
stToPrim :: PrimMonad m => ST (PrimState m) a -> m a
-- | Convert a PrimBase to another monad with a possibly different
-- state token. This operation is highly unsafe!
unsafePrimToPrim :: (PrimBase m1, PrimMonad m2) => m1 a -> m2 a
-- | Convert any PrimBase to IO. This operation is highly
-- unsafe!
unsafePrimToIO :: PrimBase m => m a -> IO a
-- | Convert any PrimBase to ST with an arbitrary state
-- token. This operation is highly unsafe!
unsafePrimToST :: PrimBase m => m a -> ST s a
-- | Convert an IO action to any PrimMonad. This operation is
-- highly unsafe!
unsafeIOToPrim :: PrimMonad m => IO a -> m a
-- | Convert an ST action with an arbitrary state token to any
-- PrimMonad. This operation is highly unsafe!
unsafeSTToPrim :: PrimMonad m => ST s a -> m a
-- | See unsafeInlineIO. This function is not recommended for the
-- same reasons.
unsafeInlinePrim :: PrimBase m => m a -> a
-- | Generally, do not use this function. It is the same as
-- accursedUnutterablePerformIO from bytestring and is
-- well behaved under narrow conditions. See the documentation of that
-- function to get an idea of when this is sound. In most cases
-- GHC.IO.Unsafe.unsafeDupablePerformIO should be preferred.
unsafeInlineIO :: IO a -> a
-- | See unsafeInlineIO. This function is not recommended for the
-- same reasons. Prefer runST when s is free.
unsafeInlineST :: ST s a -> a
-- | Ensure that the value is considered alive by the garbage collection.
-- Warning: GHC has optimization passes that can erase touch if
-- it is certain that an exception is thrown afterward. Prefer
-- keepAlive.
touch :: PrimMonad m => a -> m ()
-- | Variant of touch that keeps a value of an unlifted type (e.g.
-- MutableByteArray#) alive.
touchUnlifted :: forall m (a :: UnliftedType). PrimMonad m => a -> m ()
-- | Keep value x alive until computation k completes.
-- Warning: This primop exists for completeness, but it is difficult to
-- use correctly. Prefer keepAliveUnlifted if the value to keep
-- alive is simply a wrapper around an unlifted type (e.g.
-- ByteArray).
keepAlive :: PrimBase m => a -> m r -> m r
-- | Variant of keepAlive in which the value kept alive is of an
-- unlifted boxed type.
keepAliveUnlifted :: forall m (a :: UnliftedType) r. PrimBase m => a -> m r -> m r
-- | Create an action to force a value; generalizes evaluate
evalPrim :: forall a m. PrimMonad m => a -> m a
unsafeInterleave :: PrimBase m => m a -> m a
unsafeDupableInterleave :: PrimBase m => m a -> m a
noDuplicate :: PrimMonad m => m ()
instance (Control.Monad.Primitive.PrimBase m, Control.Monad.Primitive.MonadPrim s m) => Control.Monad.Primitive.MonadPrimBase s m
instance (Control.Monad.Primitive.PrimMonad m, s GHC.Types.~ Control.Monad.Primitive.PrimState m) => Control.Monad.Primitive.MonadPrim s m
instance Control.Monad.Primitive.PrimBase GHC.Types.IO
instance Control.Monad.Primitive.PrimBase m => Control.Monad.Primitive.PrimBase (Control.Monad.Trans.Identity.IdentityT m)
instance Control.Monad.Primitive.PrimBase (GHC.Internal.Control.Monad.ST.Lazy.Imp.ST s)
instance Control.Monad.Primitive.PrimBase (GHC.Internal.ST.ST s)
instance (GHC.Internal.Base.Monoid w, Control.Monad.Primitive.PrimMonad m) => Control.Monad.Primitive.PrimMonad (Control.Monad.Trans.Accum.AccumT w m)
instance Control.Monad.Primitive.PrimMonad m => Control.Monad.Primitive.PrimMonad (Control.Monad.Trans.Cont.ContT r m)
instance Control.Monad.Primitive.PrimMonad m => Control.Monad.Primitive.PrimMonad (Control.Monad.Trans.Except.ExceptT e m)
instance Control.Monad.Primitive.PrimMonad GHC.Types.IO
instance Control.Monad.Primitive.PrimMonad m => Control.Monad.Primitive.PrimMonad (Control.Monad.Trans.Identity.IdentityT m)
instance Control.Monad.Primitive.PrimMonad m => Control.Monad.Primitive.PrimMonad (Control.Monad.Trans.Maybe.MaybeT m)
instance (GHC.Internal.Base.Monoid w, Control.Monad.Primitive.PrimMonad m) => Control.Monad.Primitive.PrimMonad (Control.Monad.Trans.RWS.Strict.RWST r w s m)
instance (GHC.Internal.Base.Monoid w, Control.Monad.Primitive.PrimMonad m) => Control.Monad.Primitive.PrimMonad (Control.Monad.Trans.RWS.CPS.RWST r w s m)
instance (GHC.Internal.Base.Monoid w, Control.Monad.Primitive.PrimMonad m) => Control.Monad.Primitive.PrimMonad (Control.Monad.Trans.RWS.Lazy.RWST r w s m)
instance Control.Monad.Primitive.PrimMonad m => Control.Monad.Primitive.PrimMonad (Control.Monad.Trans.Reader.ReaderT r m)
instance Control.Monad.Primitive.PrimMonad (GHC.Internal.Control.Monad.ST.Lazy.Imp.ST s)
instance Control.Monad.Primitive.PrimMonad (GHC.Internal.ST.ST s)
instance Control.Monad.Primitive.PrimMonad m => Control.Monad.Primitive.PrimMonad (Control.Monad.Trans.Select.SelectT r m)
instance Control.Monad.Primitive.PrimMonad m => Control.Monad.Primitive.PrimMonad (Control.Monad.Trans.State.Strict.StateT s m)
instance Control.Monad.Primitive.PrimMonad m => Control.Monad.Primitive.PrimMonad (Control.Monad.Trans.State.Lazy.StateT s m)
instance (GHC.Internal.Base.Monoid w, Control.Monad.Primitive.PrimMonad m) => Control.Monad.Primitive.PrimMonad (Control.Monad.Trans.Writer.Strict.WriterT w m)
instance (GHC.Internal.Base.Monoid w, Control.Monad.Primitive.PrimMonad m) => Control.Monad.Primitive.PrimMonad (Control.Monad.Trans.Writer.CPS.WriterT w m)
instance (GHC.Internal.Base.Monoid w, Control.Monad.Primitive.PrimMonad m) => Control.Monad.Primitive.PrimMonad (Control.Monad.Trans.Writer.Lazy.WriterT w m)
-- | Primitive operations on MVar. This module provides a similar
-- interface to Control.Concurrent.MVar. However, the functions
-- are generalized to work in any PrimMonad instead of only
-- working in IO. Note that all of the functions here are
-- completely deterministic. Users of MVar are responsible for
-- designing abstractions that guarantee determinism in the presence of
-- multi-threading.
--
-- For a more detailed explanation, see Control.Concurrent.MVar.
module Data.Primitive.MVar
-- | A synchronizing variable, used for communication between concurrent
-- threads. It can be thought of as a box, which may be empty or full.
data MVar s a
MVar :: MVar# s a -> MVar s a
-- | Create a new MVar that holds the supplied argument.
newMVar :: PrimMonad m => a -> m (MVar (PrimState m) a)
-- | Check whether a given MVar is empty.
--
-- Notice that the boolean value returned is just a snapshot of the state
-- of the MVar. By the time you get to react on its result, the
-- MVar may have been filled (or emptied) - so be extremely
-- careful when using this operation. Use tryTakeMVar instead if
-- possible.
isEmptyMVar :: PrimMonad m => MVar (PrimState m) a -> m Bool
-- | Create a new MVar that is initially empty.
newEmptyMVar :: PrimMonad m => m (MVar (PrimState m) a)
-- | Put a value into an MVar. If the MVar is currently full,
-- putMVar will wait until it becomes empty.
--
-- There are two further important properties of putMVar:
--
--
-- - putMVar is single-wakeup. That is, if there are multiple
-- threads blocked in putMVar, and the MVar becomes empty,
-- only one thread will be woken up. The runtime guarantees that the
-- woken thread completes its putMVar operation.
-- - When multiple threads are blocked on an MVar, they are
-- woken up in FIFO order. This is useful for providing fairness
-- properties of abstractions built using MVars.
--
putMVar :: PrimMonad m => MVar (PrimState m) a -> a -> m ()
-- | Atomically read the contents of an MVar. If the MVar is
-- currently empty, readMVar will wait until it is full.
-- readMVar is guaranteed to receive the next putMVar.
--
-- Multiple Wakeup: readMVar is multiple-wakeup, so when
-- multiple readers are blocked on an MVar, all of them are woken
-- up at the same time.
--
--
-- - It is single-wakeup instead of multiple-wakeup.
-- - It might not receive the value from the next call to
-- putMVar if there is already a pending thread blocked on
-- takeMVar.
-- - If another thread puts a value in the MVar in between the
-- calls to takeMVar and putMVar, that value may be
-- overridden.
--
readMVar :: PrimMonad m => MVar (PrimState m) a -> m a
-- | Return the contents of the MVar. If the MVar is
-- currently empty, takeMVar will wait until it is full. After a
-- takeMVar, the MVar is left empty.
--
-- There are two further important properties of takeMVar:
--
--
-- - takeMVar is single-wakeup. That is, if there are multiple
-- threads blocked in takeMVar, and the MVar becomes full,
-- only one thread will be woken up. The runtime guarantees that the
-- woken thread completes its takeMVar operation.
-- - When multiple threads are blocked on an MVar, they are
-- woken up in FIFO order. This is useful for providing fairness
-- properties of abstractions built using MVars.
--
takeMVar :: PrimMonad m => MVar (PrimState m) a -> m a
-- | A non-blocking version of putMVar. The tryPutMVar
-- function attempts to put the value a into the MVar,
-- returning True if it was successful, or False otherwise.
tryPutMVar :: PrimMonad m => MVar (PrimState m) a -> a -> m Bool
-- | A non-blocking version of readMVar. The tryReadMVar
-- function returns immediately, with Nothing if the MVar
-- was empty, or Just a if the MVar was full with
-- contents a.
--
--
-- - It is single-wakeup instead of multiple-wakeup.
-- - In the presence of other threads calling putMVar,
-- tryReadMVar may block.
-- - If another thread puts a value in the MVar in between the
-- calls to tryTakeMVar and putMVar, that value may be
-- overridden.
--
tryReadMVar :: PrimMonad m => MVar (PrimState m) a -> m (Maybe a)
-- | A non-blocking version of takeMVar. The tryTakeMVar
-- function returns immediately, with Nothing if the MVar
-- was empty, or Just a if the MVar was full with
-- contents a. After tryTakeMVar, the MVar is left
-- empty.
tryTakeMVar :: PrimMonad m => MVar (PrimState m) a -> m (Maybe a)
instance GHC.Classes.Eq (Data.Primitive.MVar.MVar s a)
-- | Primitive arrays of boxed values.
module Data.Primitive.Array
-- | Boxed arrays.
data Array a
Array :: Array# a -> Array a
[array#] :: Array a -> Array# a
-- | Mutable boxed arrays associated with a primitive state token.
data MutableArray s a
MutableArray :: MutableArray# s a -> MutableArray s a
[marray#] :: MutableArray s a -> MutableArray# s a
-- | Create a new mutable array of the specified size and initialise all
-- elements with the given value.
--
-- Note: this function does not check if the input is
-- non-negative.
newArray :: PrimMonad m => Int -> a -> m (MutableArray (PrimState m) a)
-- | Read a value from the array at the given index.
--
-- Note: this function does not do bounds checking.
readArray :: PrimMonad m => MutableArray (PrimState m) a -> Int -> m a
-- | Write a value to the array at the given index.
--
-- Note: this function does not do bounds checking.
writeArray :: PrimMonad m => MutableArray (PrimState m) a -> Int -> a -> m ()
-- | Read a value from the immutable array at the given index.
--
-- Note: this function does not do bounds checking.
indexArray :: Array a -> Int -> a
-- | Read a value from the immutable array at the given index using an
-- applicative. This allows us to be strict in the array while remaining
-- lazy in the read element which is very useful for collective
-- operations. Suppose we want to copy an array. We could do something
-- like this:
--
--
-- copy marr arr ... = do ...
-- writeArray marr i (indexArray arr i) ...
-- ...
--
--
-- But since the arrays are lazy, the calls to indexArray will not
-- be evaluated. Rather, marr will be filled with thunks each of
-- which would retain a reference to arr. This is definitely not
-- what we want!
--
-- With indexArrayM, we can instead write
--
--
-- copy marr arr ... = do ...
-- x <- indexArrayM arr i
-- writeArray marr i x
-- ...
--
--
-- Now, indexing is executed immediately although the returned element is
-- still not evaluated.
--
-- Note: this function does not do bounds checking.
indexArrayM :: Applicative m => Array a -> Int -> m a
-- | Read a value from the immutable array at the given index, returning
-- the result in an unboxed unary tuple. This is currently used to
-- implement folds.
--
-- Note: this function does not do bounds checking.
indexArray## :: Array a -> Int -> (# a #)
-- | Create an immutable copy of a slice of an array.
--
-- This operation makes a copy of the specified section, so it is safe to
-- continue using the mutable array afterward.
--
-- Note: The provided array should contain the full subrange
-- specified by the two Ints, but this is not checked.
freezeArray :: PrimMonad m => MutableArray (PrimState m) a -> Int -> Int -> m (Array a)
-- | Create a mutable array from a slice of an immutable array.
--
-- This operation makes a copy of the specified slice, so it is safe to
-- use the immutable array afterward.
--
-- Note: The provided array should contain the full subrange
-- specified by the two Ints, but this is not checked.
thawArray :: PrimMonad m => Array a -> Int -> Int -> m (MutableArray (PrimState m) a)
-- | Execute the monadic action and freeze the resulting array.
--
--
-- runArray m = runST $ m >>= unsafeFreezeArray
--
runArray :: (forall s. () => ST s (MutableArray s a)) -> Array a
-- | Create an array of the given size with a default value, apply the
-- monadic function and freeze the result. If the size is 0, return
-- emptyArray (rather than a new copy thereof).
--
--
-- createArray 0 _ _ = emptyArray
-- createArray n x f = runArray $ do
-- mary <- newArray n x
-- f mary
-- pure mary
--
createArray :: Int -> a -> (forall s. () => MutableArray s a -> ST s ()) -> Array a
-- | Convert a mutable array to an immutable one without copying. The array
-- should not be modified after the conversion.
unsafeFreezeArray :: PrimMonad m => MutableArray (PrimState m) a -> m (Array a)
-- | Convert an immutable array to an mutable one without copying. The
-- immutable array should not be used after the conversion.
unsafeThawArray :: PrimMonad m => Array a -> m (MutableArray (PrimState m) a)
-- | Check whether the two arrays refer to the same memory block.
sameMutableArray :: MutableArray s a -> MutableArray s a -> Bool
-- | Copy a slice of an immutable array to a mutable array.
--
-- Note: this function does not do bounds or overlap checking.
copyArray :: PrimMonad m => MutableArray (PrimState m) a -> Int -> Array a -> Int -> Int -> m ()
-- | Copy a slice of a mutable array to another array. The two arrays may
-- overlap.
--
-- Note: this function does not do bounds or overlap checking.
copyMutableArray :: PrimMonad m => MutableArray (PrimState m) a -> Int -> MutableArray (PrimState m) a -> Int -> Int -> m ()
-- | Return a newly allocated Array with the specified subrange of
-- the provided Array.
--
-- Note: The provided array should contain the full subrange
-- specified by the two Ints, but this is not checked.
cloneArray :: Array a -> Int -> Int -> Array a
-- | Return a newly allocated MutableArray. with the specified
-- subrange of the provided MutableArray. The provided
-- MutableArray should contain the full subrange specified by the
-- two Ints, but this is not checked.
--
-- Note: The provided array should contain the full subrange
-- specified by the two Ints, but this is not checked.
cloneMutableArray :: PrimMonad m => MutableArray (PrimState m) a -> Int -> Int -> m (MutableArray (PrimState m) a)
-- | The number of elements in an immutable array.
sizeofArray :: Array a -> Int
-- | The number of elements in a mutable array.
sizeofMutableArray :: MutableArray s a -> Int
-- | The empty Array.
emptyArray :: Array a
-- | Create an array from a list of a known length. If the length of the
-- list does not match the given length, this throws an exception.
arrayFromListN :: Int -> [a] -> Array a
-- | Create an array from a list.
arrayFromList :: [a] -> Array a
-- | Strict map over the elements of the array.
mapArray' :: (a -> b) -> Array a -> Array b
-- | This is the fastest, most straightforward way to traverse an array,
-- but it only works correctly with a sufficiently "affine"
-- PrimMonad instance. In particular, it must only produce
-- one result array. ListT-transformed monads, for example,
-- will not work right at all.
traverseArrayP :: PrimMonad m => (a -> m b) -> Array a -> m (Array b)
instance GHC.Internal.Base.Alternative Data.Primitive.Array.Array
instance GHC.Internal.Base.Applicative Data.Primitive.Array.Array
instance GHC.Internal.Data.Data.Data a => GHC.Internal.Data.Data.Data (Data.Primitive.Array.Array a)
instance (GHC.Internal.Data.Typeable.Internal.Typeable s, GHC.Internal.Data.Typeable.Internal.Typeable a) => GHC.Internal.Data.Data.Data (Data.Primitive.Array.MutableArray s a)
instance Data.Functor.Classes.Eq1 Data.Primitive.Array.Array
instance GHC.Classes.Eq a => GHC.Classes.Eq (Data.Primitive.Array.Array a)
instance GHC.Classes.Eq (Data.Primitive.Array.MutableArray s a)
instance GHC.Internal.Data.Foldable.Foldable Data.Primitive.Array.Array
instance GHC.Internal.Base.Functor Data.Primitive.Array.Array
instance GHC.Internal.IsList.IsList (Data.Primitive.Array.Array a)
instance Language.Haskell.TH.Syntax.Lift a => Language.Haskell.TH.Syntax.Lift (Data.Primitive.Array.Array a)
instance GHC.Internal.Base.Monad Data.Primitive.Array.Array
instance GHC.Internal.Control.Monad.Fail.MonadFail Data.Primitive.Array.Array
instance GHC.Internal.Control.Monad.Fix.MonadFix Data.Primitive.Array.Array
instance GHC.Internal.Base.MonadPlus Data.Primitive.Array.Array
instance Control.Monad.Zip.MonadZip Data.Primitive.Array.Array
instance GHC.Internal.Base.Monoid (Data.Primitive.Array.Array a)
instance Control.DeepSeq.NFData1 Data.Primitive.Array.Array
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Data.Primitive.Array.Array a)
instance Data.Functor.Classes.Ord1 Data.Primitive.Array.Array
instance GHC.Classes.Ord a => GHC.Classes.Ord (Data.Primitive.Array.Array a)
instance Data.Functor.Classes.Read1 Data.Primitive.Array.Array
instance GHC.Internal.Read.Read a => GHC.Internal.Read.Read (Data.Primitive.Array.Array a)
instance GHC.Internal.Base.Semigroup (Data.Primitive.Array.Array a)
instance Data.Functor.Classes.Show1 Data.Primitive.Array.Array
instance GHC.Internal.Show.Show a => GHC.Internal.Show.Show (Data.Primitive.Array.Array a)
instance GHC.Internal.Data.Traversable.Traversable Data.Primitive.Array.Array
-- | Primitive boxed mutable variables. This is a generalization of
-- Data.IORef, Data.STRef and Data.STRef.Lazy to
-- work in any PrimMonad.
module Data.Primitive.MutVar
-- | A MutVar behaves like a single-element mutable array associated
-- with a primitive state token.
data MutVar s a
MutVar :: MutVar# s a -> MutVar s a
-- | Create a new MutVar with the specified initial value.
newMutVar :: PrimMonad m => a -> m (MutVar (PrimState m) a)
-- | Read the value of a MutVar.
readMutVar :: PrimMonad m => MutVar (PrimState m) a -> m a
-- | Write a new value into a MutVar.
writeMutVar :: PrimMonad m => MutVar (PrimState m) a -> a -> m ()
-- | Atomically mutate the contents of a MutVar.
--
-- This function is useful for using MutVar in a safe way in a
-- multithreaded program. If you only have one MutVar, then using
-- atomicModifyMutVar to access and modify it will prevent race
-- conditions.
--
-- Extending the atomicity to multiple MutVars is problematic, so
-- if you need to do anything more complicated, using MVar instead
-- is a good idea.
--
-- atomicModifyMutVar does not apply the function strictly. This
-- means if a program calls atomicModifyMutVar many times, but
-- seldom uses the value, thunks will pile up in memory resulting in a
-- space leak. To avoid this problem, use atomicModifyMutVar'
-- instead.
atomicModifyMutVar :: PrimMonad m => MutVar (PrimState m) a -> (a -> (a, b)) -> m b
-- | Strict version of atomicModifyMutVar. This forces both the
-- value stored in the MutVar as well as the value returned.
atomicModifyMutVar' :: PrimMonad m => MutVar (PrimState m) a -> (a -> (a, b)) -> m b
-- | Mutate the contents of a MutVar.
--
-- modifyMutVar does not apply the function strictly. This means
-- if a program calls modifyMutVar many times, but seldom uses the
-- value, thunks will pile up in memory resulting in a space leak. To
-- avoid this problem, use modifyMutVar' instead.
modifyMutVar :: PrimMonad m => MutVar (PrimState m) a -> (a -> a) -> m ()
-- | Strict version of modifyMutVar.
modifyMutVar' :: PrimMonad m => MutVar (PrimState m) a -> (a -> a) -> m ()
-- | Convert MutVar to IORef
mutVarFromIORef :: IORef a -> MutVar RealWorld a
-- | Convert MutVar to IORef
mutVarToIORef :: MutVar RealWorld a -> IORef a
-- | Convert MutVar to STRef
mutVarFromSTRef :: STRef s a -> MutVar s a
-- | Convert MutVar to STRef
mutVarToSTRef :: MutVar s a -> STRef s a
instance GHC.Classes.Eq (Data.Primitive.MutVar.MutVar s a)
-- | Small arrays are boxed (im)mutable arrays.
--
-- The underlying structure of the Array type contains a card
-- table, allowing segments of the array to be marked as having been
-- mutated. This allows the garbage collector to only re-traverse
-- segments of the array that have been marked during certain phases,
-- rather than having to traverse the entire array.
--
-- SmallArray lacks this table. This means that it takes up less
-- memory and has slightly faster writes. It is also more efficient
-- during garbage collection so long as the card table would have a
-- single entry covering the entire array. These advantages make them
-- suitable for use as arrays that are known to be small.
--
-- The card size is 128, so for uses much larger than that, Array
-- would likely be superior.
module Data.Primitive.SmallArray
data SmallArray a
SmallArray :: SmallArray# a -> SmallArray a
data SmallMutableArray s a
SmallMutableArray :: SmallMutableArray# s a -> SmallMutableArray s a
-- | Create a new small mutable array.
--
-- Note: this function does not check if the input is
-- non-negative.
newSmallArray :: PrimMonad m => Int -> a -> m (SmallMutableArray (PrimState m) a)
-- | Read the element at a given index in a mutable array.
--
-- Note: this function does not do bounds checking.
readSmallArray :: PrimMonad m => SmallMutableArray (PrimState m) a -> Int -> m a
-- | Write an element at the given idex in a mutable array.
--
-- Note: this function does not do bounds checking.
writeSmallArray :: PrimMonad m => SmallMutableArray (PrimState m) a -> Int -> a -> m ()
-- | Copy a slice of an immutable array into a mutable array.
--
-- Note: this function does not do bounds or overlap checking.
copySmallArray :: PrimMonad m => SmallMutableArray (PrimState m) a -> Int -> SmallArray a -> Int -> Int -> m ()
-- | Copy a slice of one mutable array into another.
--
-- Note: this function does not do bounds or overlap checking.
copySmallMutableArray :: PrimMonad m => SmallMutableArray (PrimState m) a -> Int -> SmallMutableArray (PrimState m) a -> Int -> Int -> m ()
-- | Look up an element in an immutable array.
--
-- Note: this function does not do bounds checking.
indexSmallArray :: SmallArray a -> Int -> a
-- | Look up an element in an immutable array.
--
-- The purpose of returning a result using an applicative is to allow the
-- caller to avoid retaining references to the array. Evaluating the
-- return value will cause the array lookup to be performed, even though
-- it may not require the element of the array to be evaluated (which
-- could throw an exception). For instance:
--
--
-- data Box a = Box a
-- ...
--
-- f sa = case indexSmallArrayM sa 0 of
-- Box x -> ...
--
--
-- x is not a closure that references sa as it would be
-- if we instead wrote:
--
--
-- let x = indexSmallArray sa 0
--
--
-- It also does not prevent sa from being garbage collected.
--
-- Note that Identity is not adequate for this use, as it is a
-- newtype, and cannot be evaluated without evaluating the element.
--
-- Note: this function does not do bounds checking.
indexSmallArrayM :: Applicative m => SmallArray a -> Int -> m a
-- | Read a value from the immutable array at the given index, returning
-- the result in an unboxed unary tuple. This is currently used to
-- implement folds.
--
-- Note: this function does not do bounds checking.
indexSmallArray## :: SmallArray a -> Int -> (# a #)
-- | Create a copy of a slice of an immutable array.
--
-- Note: The provided array should contain the full subrange
-- specified by the two Ints, but this is not checked.
cloneSmallArray :: SmallArray a -> Int -> Int -> SmallArray a
-- | Create a copy of a slice of a mutable array.
--
-- Note: The provided array should contain the full subrange
-- specified by the two Ints, but this is not checked.
cloneSmallMutableArray :: PrimMonad m => SmallMutableArray (PrimState m) a -> Int -> Int -> m (SmallMutableArray (PrimState m) a)
-- | Create an immutable array corresponding to a slice of a mutable array.
--
-- This operation copies the portion of the array to be frozen.
--
-- Note: The provided array should contain the full subrange
-- specified by the two Ints, but this is not checked.
freezeSmallArray :: PrimMonad m => SmallMutableArray (PrimState m) a -> Int -> Int -> m (SmallArray a)
-- | Render a mutable array immutable.
--
-- This operation performs no copying, so care must be taken not to
-- modify the input array after freezing.
unsafeFreezeSmallArray :: PrimMonad m => SmallMutableArray (PrimState m) a -> m (SmallArray a)
-- | Create a mutable array corresponding to a slice of an immutable array.
--
-- This operation copies the portion of the array to be thawed.
--
-- Note: The provided array should contain the full subrange
-- specified by the two Ints, but this is not checked.
thawSmallArray :: PrimMonad m => SmallArray a -> Int -> Int -> m (SmallMutableArray (PrimState m) a)
-- | Render an immutable array mutable.
--
-- This operation performs no copying, so care must be taken with its
-- use.
unsafeThawSmallArray :: PrimMonad m => SmallArray a -> m (SmallMutableArray (PrimState m) a)
-- | Execute the monadic action and freeze the resulting array.
--
--
-- runSmallArray m = runST $ m >>= unsafeFreezeSmallArray
--
runSmallArray :: (forall s. () => ST s (SmallMutableArray s a)) -> SmallArray a
-- | Create an array of the given size with a default value, apply the
-- monadic function and freeze the result. If the size is 0, return
-- emptySmallArray (rather than a new copy thereof).
--
--
-- createSmallArray 0 _ _ = emptySmallArray
-- createSmallArray n x f = runSmallArray $ do
-- mary <- newSmallArray n x
-- f mary
-- pure mary
--
createSmallArray :: Int -> a -> (forall s. () => SmallMutableArray s a -> ST s ()) -> SmallArray a
-- | The number of elements in an immutable array.
sizeofSmallArray :: SmallArray a -> Int
-- | Get the number of elements in a mutable array. Unlike
-- sizeofSmallMutableArray, this function will be sure to produce
-- the correct result if SmallMutableArray has been shrunk in
-- place. Consider the following:
--
--
-- do
-- sa <- newSmallArray 10 x
-- print $ sizeofSmallMutableArray sa
-- shrinkSmallMutableArray sa 5
-- print $ sizeofSmallMutableArray sa
--
--
-- The compiler is well within its rights to eliminate the second size
-- check and print 10 twice. However,
-- getSizeofSmallMutableArray will check the size each time it's
-- executed (not evaluated), so it won't have this problem:
--
--
-- do
-- sa <- newSmallArray 10 x
-- print =<< getSizeofSmallMutableArray sa
-- shrinkSmallMutableArray sa 5
-- print =<< getSizeofSmallMutableArray sa
--
--
-- will certainly print 10 and then 5.
getSizeofSmallMutableArray :: PrimMonad m => SmallMutableArray (PrimState m) a -> m Int
-- | The number of elements in a mutable array. This should only be used
-- for arrays that are not shrunk in place.
--
-- This is deprecated and will be removed in a future release. Use
-- getSizeofSmallMutableArray instead.
-- | Deprecated: use getSizeofSmallMutableArray instead
sizeofSmallMutableArray :: SmallMutableArray s a -> Int
-- | Shrink the mutable array in place. The size given must be equal to or
-- less than the current size of the array. This is not checked.
shrinkSmallMutableArray :: PrimMonad m => SmallMutableArray (PrimState m) a -> Int -> m ()
-- | Resize a mutable array to new specified size. The returned
-- SmallMutableArray is either the original
-- SmallMutableArray resized in-place or, if not possible, a newly
-- allocated SmallMutableArray with the original content copied
-- over.
--
-- To avoid undefined behaviour, the original SmallMutableArray
-- shall not be accessed anymore after a resizeSmallMutableArray
-- has been performed. Moreover, no reference to the old one should be
-- kept in order to allow garbage collection of the original
-- SmallMutableArray in case a new SmallMutableArray had to
-- be allocated.
resizeSmallMutableArray :: PrimMonad m => SmallMutableArray (PrimState m) a -> Int -> a -> m (SmallMutableArray (PrimState m) a)
-- | The empty SmallArray.
emptySmallArray :: SmallArray a
-- | Create a SmallArray from a list.
smallArrayFromList :: [a] -> SmallArray a
-- | Create a SmallArray from a list of a known length. If the
-- length of the list does not match the given length, this throws an
-- exception.
smallArrayFromListN :: Int -> [a] -> SmallArray a
-- | Strict map over the elements of the array.
mapSmallArray' :: (a -> b) -> SmallArray a -> SmallArray b
-- | This is the fastest, most straightforward way to traverse an array,
-- but it only works correctly with a sufficiently "affine"
-- PrimMonad instance. In particular, it must only produce
-- one result array. ListT-transformed monads, for example,
-- will not work right at all.
traverseSmallArrayP :: PrimMonad m => (a -> m b) -> SmallArray a -> m (SmallArray b)
instance GHC.Internal.Base.Alternative Data.Primitive.SmallArray.SmallArray
instance GHC.Internal.Base.Applicative Data.Primitive.SmallArray.SmallArray
instance GHC.Internal.Data.Data.Data a => GHC.Internal.Data.Data.Data (Data.Primitive.SmallArray.SmallArray a)
instance (GHC.Internal.Data.Typeable.Internal.Typeable s, GHC.Internal.Data.Typeable.Internal.Typeable a) => GHC.Internal.Data.Data.Data (Data.Primitive.SmallArray.SmallMutableArray s a)
instance Data.Functor.Classes.Eq1 Data.Primitive.SmallArray.SmallArray
instance GHC.Classes.Eq a => GHC.Classes.Eq (Data.Primitive.SmallArray.SmallArray a)
instance GHC.Classes.Eq (Data.Primitive.SmallArray.SmallMutableArray s a)
instance GHC.Internal.Data.Foldable.Foldable Data.Primitive.SmallArray.SmallArray
instance GHC.Internal.Base.Functor Data.Primitive.SmallArray.SmallArray
instance GHC.Internal.IsList.IsList (Data.Primitive.SmallArray.SmallArray a)
instance Language.Haskell.TH.Syntax.Lift a => Language.Haskell.TH.Syntax.Lift (Data.Primitive.SmallArray.SmallArray a)
instance GHC.Internal.Control.Monad.Fail.MonadFail Data.Primitive.SmallArray.SmallArray
instance GHC.Internal.Control.Monad.Fix.MonadFix Data.Primitive.SmallArray.SmallArray
instance GHC.Internal.Base.MonadPlus Data.Primitive.SmallArray.SmallArray
instance GHC.Internal.Base.Monad Data.Primitive.SmallArray.SmallArray
instance Control.Monad.Zip.MonadZip Data.Primitive.SmallArray.SmallArray
instance GHC.Internal.Base.Monoid (Data.Primitive.SmallArray.SmallArray a)
instance Control.DeepSeq.NFData1 Data.Primitive.SmallArray.SmallArray
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Data.Primitive.SmallArray.SmallArray a)
instance Data.Functor.Classes.Ord1 Data.Primitive.SmallArray.SmallArray
instance GHC.Classes.Ord a => GHC.Classes.Ord (Data.Primitive.SmallArray.SmallArray a)
instance Data.Functor.Classes.Read1 Data.Primitive.SmallArray.SmallArray
instance GHC.Internal.Read.Read a => GHC.Internal.Read.Read (Data.Primitive.SmallArray.SmallArray a)
instance GHC.Internal.Base.Semigroup (Data.Primitive.SmallArray.SmallArray a)
instance Data.Functor.Classes.Show1 Data.Primitive.SmallArray.SmallArray
instance GHC.Internal.Show.Show a => GHC.Internal.Show.Show (Data.Primitive.SmallArray.SmallArray a)
instance GHC.Internal.Data.Traversable.Traversable Data.Primitive.SmallArray.SmallArray
-- | Basic types and classes for primitive array operations.
module Data.Primitive.Types
-- | Class of types supporting primitive array operations. This includes
-- interfacing with GC-managed memory (functions suffixed with
-- ByteArray#) and interfacing with unmanaged memory (functions
-- suffixed with Addr#). Endianness is platform-dependent.
class Prim a
-- | The size of values of type a in bytes. This has to be used
-- with TypeApplications: sizeOfType @a.
sizeOfType# :: Prim a => Proxy a -> Int#
-- | The size of values of type a in bytes. The argument is not
-- used.
--
-- It is recommended to use sizeOfType# instead.
sizeOf# :: Prim a => a -> Int#
-- | The alignment of values of type a in bytes. This has to be
-- used with TypeApplications: alignmentOfType @a.
alignmentOfType# :: Prim a => Proxy a -> Int#
-- | The alignment of values of type a in bytes. The argument is
-- not used.
--
-- It is recommended to use alignmentOfType# instead.
alignment# :: Prim a => a -> Int#
-- | Read a value from the array. The offset is in elements of type
-- a rather than in bytes.
indexByteArray# :: Prim a => ByteArray# -> Int# -> a
-- | Read a value from the mutable array. The offset is in elements of type
-- a rather than in bytes.
readByteArray# :: Prim a => MutableByteArray# s -> Int# -> State# s -> (# State# s, a #)
-- | Write a value to the mutable array. The offset is in elements of type
-- a rather than in bytes.
writeByteArray# :: Prim a => MutableByteArray# s -> Int# -> a -> State# s -> State# s
-- | Fill a slice of the mutable array with a value. The offset and length
-- of the chunk are in elements of type a rather than in bytes.
setByteArray# :: Prim a => MutableByteArray# s -> Int# -> Int# -> a -> State# s -> State# s
-- | Read a value from a memory position given by an address and an offset.
-- The memory block the address refers to must be immutable. The offset
-- is in elements of type a rather than in bytes.
indexOffAddr# :: Prim a => Addr# -> Int# -> a
-- | Read a value from a memory position given by an address and an offset.
-- The offset is in elements of type a rather than in bytes.
readOffAddr# :: Prim a => Addr# -> Int# -> State# s -> (# State# s, a #)
-- | Write a value to a memory position given by an address and an offset.
-- The offset is in elements of type a rather than in bytes.
writeOffAddr# :: Prim a => Addr# -> Int# -> a -> State# s -> State# s
-- | Fill a memory block given by an address, an offset and a length. The
-- offset and length are in elements of type a rather than in
-- bytes.
setOffAddr# :: Prim a => Addr# -> Int# -> Int# -> a -> State# s -> State# s
-- | The size of values of type a in bytes. The argument is not
-- used.
--
-- It is recommended to use sizeOfType instead.
--
-- This function has existed since 0.1, but was moved from
-- Primitive to Types in version 0.6.3.0.
sizeOf :: Prim a => a -> Int
-- | The size of values of type a in bytes. This has to be used
-- with TypeApplications: sizeOfType @a.
--
--
-- >>> :set -XTypeApplications
--
-- >>> import Data.Int (Int32)
--
-- >>> sizeOfType @Int32
-- 4
--
sizeOfType :: Prim a => Int
-- | The alignment of values of type a in bytes. The argument is
-- not used.
--
-- It is recommended to use alignmentOfType instead.
--
-- This function has existed since 0.1, but was moved from
-- Primitive to Types in version 0.6.3.0.
alignment :: Prim a => a -> Int
-- | The alignment of values of type a in bytes. This has to be
-- used with TypeApplications: alignmentOfType @a.
alignmentOfType :: Prim a => Int
-- | An implementation of setByteArray# that calls
-- writeByteArray# to set each element. This is helpful when
-- writing a Prim instance for a multi-word data type for which
-- there is no CPU-accelerated way to broadcast a value to contiguous
-- memory. It is typically used alongside defaultSetOffAddr#. For
-- example:
--
--
-- data Trip = Trip Int Int Int
--
-- instance Prim Trip
-- sizeOfType# _ = 3# *# sizeOfType# (proxy# :: Proxy# Int)
-- alignmentOfType# _ = alignmentOfType# (proxy# :: Proxy# Int)
-- indexByteArray# arr# i# = ...
-- readByteArray# arr# i# = ...
-- writeByteArray# arr# i# (Trip a b c) =
-- \s0 -> case writeByteArray# arr# (3# *# i#) a s0 of
-- s1 -> case writeByteArray# arr# ((3# *# i#) +# 1#) b s1 of
-- s2 -> case writeByteArray# arr# ((3# *# i#) +# 2# ) c s2 of
-- s3 -> s3
-- setByteArray# = defaultSetByteArray#
-- indexOffAddr# addr# i# = ...
-- readOffAddr# addr# i# = ...
-- writeOffAddr# addr# i# (Trip a b c) =
-- \s0 -> case writeOffAddr# addr# (3# *# i#) a s0 of
-- s1 -> case writeOffAddr# addr# ((3# *# i#) +# 1#) b s1 of
-- s2 -> case writeOffAddr# addr# ((3# *# i#) +# 2# ) c s2 of
-- s3 -> s3
-- setOffAddr# = defaultSetOffAddr#
--
defaultSetByteArray# :: Prim a => MutableByteArray# s -> Int# -> Int# -> a -> State# s -> State# s
-- | An implementation of setOffAddr# that calls
-- writeOffAddr# to set each element. The documentation of
-- defaultSetByteArray# provides an example of how to use this.
defaultSetOffAddr# :: Prim a => Addr# -> Int# -> Int# -> a -> State# s -> State# s
-- | Newtype that uses a Prim instance to give rise to a
-- Storable instance. This type is intended to be used with the
-- DerivingVia extension available in GHC 8.6 and up. For
-- example, consider a user-defined Prim instance for a multi-word
-- data type.
--
--
-- data Uuid = Uuid Word64 Word64
-- deriving Storable via (PrimStorable Uuid)
-- instance Prim Uuid where ...
--
--
-- Writing the Prim instance is tedious and unavoidable, but the
-- Storable instance comes for free once the Prim instance
-- is written.
newtype PrimStorable a
PrimStorable :: a -> PrimStorable a
[getPrimStorable] :: PrimStorable a -> a
-- | A value of type Ptr a represents a pointer to an
-- object, or an array of objects, which may be marshalled to or from
-- Haskell values of type a.
--
-- The type a will often be an instance of class Storable
-- which provides the marshalling operations. However this is not
-- essential, and you can provide your own operations to access the
-- pointer. For example you might write small foreign functions to get or
-- set the fields of a C struct.
data Ptr a
Ptr :: Addr# -> Ptr a
instance Data.Primitive.Types.Prim GHC.Internal.System.Posix.Types.CBlkCnt
instance Data.Primitive.Types.Prim GHC.Internal.System.Posix.Types.CBlkSize
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.C.Types.CBool
instance Data.Primitive.Types.Prim GHC.Internal.System.Posix.Types.CCc
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.C.Types.CChar
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.C.Types.CClock
instance Data.Primitive.Types.Prim GHC.Internal.System.Posix.Types.CClockId
instance Data.Primitive.Types.Prim GHC.Internal.System.Posix.Types.CDev
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.C.Types.CDouble
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.C.Types.CFloat
instance Data.Primitive.Types.Prim GHC.Internal.System.Posix.Types.CFsBlkCnt
instance Data.Primitive.Types.Prim GHC.Internal.System.Posix.Types.CFsFilCnt
instance Data.Primitive.Types.Prim GHC.Internal.System.Posix.Types.CGid
instance Data.Primitive.Types.Prim GHC.Internal.System.Posix.Types.CId
instance Data.Primitive.Types.Prim GHC.Internal.System.Posix.Types.CIno
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.C.Types.CInt
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.C.Types.CIntMax
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.C.Types.CIntPtr
instance Data.Primitive.Types.Prim GHC.Internal.System.Posix.Types.CKey
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.C.Types.CLLong
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.C.Types.CLong
instance Data.Primitive.Types.Prim GHC.Internal.System.Posix.Types.CMode
instance Data.Primitive.Types.Prim GHC.Internal.System.Posix.Types.CNlink
instance Data.Primitive.Types.Prim GHC.Internal.System.Posix.Types.COff
instance Data.Primitive.Types.Prim GHC.Internal.System.Posix.Types.CPid
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.C.Types.CPtrdiff
instance Data.Primitive.Types.Prim GHC.Internal.System.Posix.Types.CRLim
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.C.Types.CSChar
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.C.Types.CSUSeconds
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.C.Types.CShort
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.C.Types.CSigAtomic
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.C.Types.CSize
instance Data.Primitive.Types.Prim GHC.Internal.System.Posix.Types.CSpeed
instance Data.Primitive.Types.Prim GHC.Internal.System.Posix.Types.CSsize
instance Data.Primitive.Types.Prim GHC.Internal.System.Posix.Types.CTcflag
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.C.Types.CTime
instance Data.Primitive.Types.Prim GHC.Internal.System.Posix.Types.CTimer
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.C.Types.CUChar
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.C.Types.CUInt
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.C.Types.CUIntMax
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.C.Types.CUIntPtr
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.C.Types.CULLong
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.C.Types.CULong
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.C.Types.CUSeconds
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.C.Types.CUShort
instance Data.Primitive.Types.Prim GHC.Internal.System.Posix.Types.CUid
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.C.Types.CWchar
instance Data.Primitive.Types.Prim GHC.Types.Char
instance Data.Primitive.Types.Prim a => Data.Primitive.Types.Prim (Data.Complex.Complex a)
instance Data.Primitive.Types.Prim a => Data.Primitive.Types.Prim (GHC.Internal.Data.Functor.Const.Const a b)
instance Data.Primitive.Types.Prim GHC.Types.Double
instance Data.Primitive.Types.Prim a => Data.Primitive.Types.Prim (GHC.Internal.Data.Ord.Down a)
instance Data.Primitive.Types.Prim a => Data.Primitive.Types.Prim (GHC.Internal.Data.Semigroup.Internal.Dual a)
instance Data.Primitive.Types.Prim GHC.Internal.System.Posix.Types.Fd
instance Data.Primitive.Types.Prim a => Data.Primitive.Types.Prim (Data.Semigroup.First a)
instance Data.Primitive.Types.Prim GHC.Types.Float
instance Data.Primitive.Types.Prim (GHC.Internal.Ptr.FunPtr a)
instance Data.Primitive.Types.Prim a => Data.Primitive.Types.Prim (GHC.Internal.Data.Functor.Identity.Identity a)
instance Data.Primitive.Types.Prim GHC.Types.Int
instance Data.Primitive.Types.Prim GHC.Internal.Int.Int16
instance Data.Primitive.Types.Prim GHC.Internal.Int.Int32
instance Data.Primitive.Types.Prim GHC.Internal.Int.Int64
instance Data.Primitive.Types.Prim GHC.Internal.Int.Int8
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.Ptr.IntPtr
instance Data.Primitive.Types.Prim a => Data.Primitive.Types.Prim (Data.Semigroup.Last a)
instance Data.Primitive.Types.Prim a => Data.Primitive.Types.Prim (Data.Semigroup.Max a)
instance Data.Primitive.Types.Prim a => Data.Primitive.Types.Prim (Data.Semigroup.Min a)
instance Data.Primitive.Types.Prim a => Data.Primitive.Types.Prim (GHC.Internal.Data.Semigroup.Internal.Product a)
instance Data.Primitive.Types.Prim (GHC.Internal.Ptr.Ptr a)
instance Data.Primitive.Types.Prim (GHC.Internal.Stable.StablePtr a)
instance Data.Primitive.Types.Prim a => Data.Primitive.Types.Prim (GHC.Internal.Data.Semigroup.Internal.Sum a)
instance Data.Primitive.Types.Prim GHC.Types.Word
instance Data.Primitive.Types.Prim GHC.Internal.Word.Word16
instance Data.Primitive.Types.Prim GHC.Internal.Word.Word32
instance Data.Primitive.Types.Prim GHC.Internal.Word.Word64
instance Data.Primitive.Types.Prim GHC.Internal.Word.Word8
instance Data.Primitive.Types.Prim GHC.Internal.Foreign.Ptr.WordPtr
instance Data.Primitive.Types.Prim a => GHC.Internal.Foreign.Storable.Storable (Data.Primitive.Types.PrimStorable a)
-- | Primitive operations on byte arrays. Most functions in this module
-- include an element type in their type signature and interpret the unit
-- for offsets and lengths as that element. A few functions (e.g.
-- copyByteArray, freezeByteArray) do not include an
-- element type. Such functions interpret offsets and lengths as units of
-- 8-bit words.
module Data.Primitive.ByteArray
-- | Lifted wrapper for ByteArray#.
--
-- Since ByteArray# is an unlifted type and not a member of kind
-- Type, things like [ByteArray#] or IO
-- ByteArray# are ill-typed. To work around this inconvenience this
-- module provides a standard lifted wrapper, inhabiting Type.
-- Clients are expected to use ByteArray in higher-level APIs, but
-- wrap and unwrap ByteArray internally as they please and use
-- functions from GHC.Exts.
data ByteArray
ByteArray :: ByteArray# -> ByteArray
-- | Lifted wrapper for MutableByteArray#.
--
-- Since MutableByteArray# is an unlifted type and not a member of
-- kind Type, things like [MutableByteArray#] or IO
-- MutableByteArray# are ill-typed. To work around this
-- inconvenience this module provides a standard lifted wrapper,
-- inhabiting Type. Clients are expected to use
-- MutableByteArray in higher-level APIs, but wrap and unwrap
-- MutableByteArray internally as they please and use functions
-- from GHC.Exts.
data MutableByteArray s
MutableByteArray :: MutableByteArray# s -> MutableByteArray s
-- | A boxed, unlifted datatype representing a region of raw memory in the
-- garbage-collected heap, which is not scanned for pointers during
-- garbage collection.
--
-- It is created by freezing a MutableByteArray# with
-- unsafeFreezeByteArray#. Freezing is essentially a no-op, as
-- MutableByteArray# and ByteArray# share the same heap
-- structure under the hood.
--
-- The immutable and mutable variants are commonly used for scenarios
-- requiring high-performance data structures, like Text,
-- Primitive Vector, Unboxed Array, and
-- ShortByteString.
--
-- Another application of fundamental importance is Integer,
-- which is backed by ByteArray#.
--
-- The representation on the heap of a Byte Array is:
--
--
-- +------------+-----------------+-----------------------+
-- | | | |
-- | HEADER | SIZE (in bytes) | PAYLOAD |
-- | | | |
-- +------------+-----------------+-----------------------+
--
--
-- To obtain a pointer to actual payload (e.g., for FFI purposes) use
-- byteArrayContents# or mutableByteArrayContents#.
--
-- Alternatively, enabling the UnliftedFFITypes extension allows
-- to mention ByteArray# and MutableByteArray# in FFI type
-- signatures directly.
data ByteArray# :: UnliftedType
-- | A mutable ByteAray#. It can be created in three ways:
--
--
--
-- Unpinned arrays can be moved around during garbage collection, so you
-- must not store or pass pointers to these values if there is a chance
-- for the garbage collector to kick in. That said, even unpinned arrays
-- can be passed to unsafe FFI calls, because no garbage collection
-- happens during these unsafe calls (see Guaranteed Call Safety
-- in the GHC Manual). For safe FFI calls, byte arrays must be not only
-- pinned, but also kept alive by means of the keepAlive# function for
-- the duration of a call (that's because garbage collection cannot move
-- a pinned array, but is free to scrap it altogether).
data MutableByteArray# a :: UnliftedType
-- | Create a new mutable byte array of the specified size in bytes. The
-- underlying memory is left uninitialized.
--
-- Note: this function does not check if the input is
-- non-negative.
newByteArray :: PrimMonad m => Int -> m (MutableByteArray (PrimState m))
-- | Create a pinned byte array of the specified size in bytes. The
-- garbage collector is guaranteed not to move it. The underlying memory
-- is left uninitialized.
--
-- Note: this function does not check if the input is
-- non-negative.
newPinnedByteArray :: PrimMonad m => Int -> m (MutableByteArray (PrimState m))
-- | Create a pinned byte array of the specified size in bytes and
-- with the given alignment. The garbage collector is guaranteed not to
-- move it. The underlying memory is left uninitialized.
--
-- Note: this function does not check if the input is
-- non-negative.
newAlignedPinnedByteArray :: PrimMonad m => Int -> Int -> m (MutableByteArray (PrimState m))
-- | Resize a mutable byte array. The new size is given in bytes.
--
-- This will either resize the array in-place or, if not possible,
-- allocate the contents into a new, unpinned array and copy the original
-- array's contents.
--
-- To avoid undefined behaviour, the original MutableByteArray
-- shall not be accessed anymore after a resizeMutableByteArray
-- has been performed. Moreover, no reference to the old one should be
-- kept in order to allow garbage collection of the original
-- MutableByteArray in case a new MutableByteArray had to
-- be allocated.
resizeMutableByteArray :: PrimMonad m => MutableByteArray (PrimState m) -> Int -> m (MutableByteArray (PrimState m))
-- | Shrink a mutable byte array. The new size is given in bytes. It must
-- be smaller than the old size. The array will be resized in place.
shrinkMutableByteArray :: PrimMonad m => MutableByteArray (PrimState m) -> Int -> m ()
-- | Read a primitive value from the byte array. The offset is given in
-- elements of type a rather than in bytes.
--
-- Note: this function does not do bounds checking.
readByteArray :: (Prim a, PrimMonad m) => MutableByteArray (PrimState m) -> Int -> m a
-- | Write a primitive value to the byte array. The offset is given in
-- elements of type a rather than in bytes.
--
-- Note: this function does not do bounds checking.
writeByteArray :: (Prim a, PrimMonad m) => MutableByteArray (PrimState m) -> Int -> a -> m ()
-- | Read a primitive value from the byte array. The offset is given in
-- elements of type a rather than in bytes.
--
-- Note: this function does not do bounds checking.
indexByteArray :: Prim a => ByteArray -> Int -> a
-- | Read an 8-bit element from the byte array, interpreting it as a
-- Latin-1-encoded character. The offset is given in bytes.
--
-- Note: this function does not do bounds checking.
readCharArray :: PrimMonad m => MutableByteArray (PrimState m) -> Int -> m Char
-- | Write a character to the byte array, encoding it with Latin-1 as a
-- single byte. Behavior is undefined for codepoints outside of the ASCII
-- and Latin-1 blocks. The offset is given in bytes.
--
-- Note: this function does not do bounds checking.
writeCharArray :: PrimMonad m => MutableByteArray (PrimState m) -> Int -> Char -> m ()
-- | Read an 8-bit element from the byte array, interpreting it as a
-- Latin-1-encoded character. The offset is given in bytes.
--
-- Note: this function does not do bounds checking.
indexCharArray :: ByteArray -> Int -> Char
-- | The empty ByteArray.
emptyByteArray :: ByteArray
-- | Create a ByteArray from a list.
--
--
-- byteArrayFromList xs = byteArrayFromListN (length xs) xs
--
byteArrayFromList :: Prim a => [a] -> ByteArray
-- | Create a ByteArray from a list of a known length. If the length
-- of the list does not match the given length, this throws an exception.
byteArrayFromListN :: Prim a => Int -> [a] -> ByteArray
-- | Right-fold over the elements of a ByteArray.
foldrByteArray :: Prim a => (a -> b -> b) -> b -> ByteArray -> b
-- | Lexicographic comparison of equal-length slices into two byte arrays.
-- This wraps the compareByteArrays# primop, which wraps
-- memcmp.
compareByteArrays :: ByteArray -> Int -> ByteArray -> Int -> Int -> Ordering
-- | Create an immutable copy of a slice of a byte array. The offset and
-- length are given in bytes.
--
-- This operation makes a copy of the specified section, so it is safe to
-- continue using the mutable array afterward.
--
-- Note: The provided array should contain the full subrange
-- specified by the two Ints, but this is not checked.
freezeByteArray :: PrimMonad m => MutableByteArray (PrimState m) -> Int -> Int -> m ByteArray
-- | Create a mutable byte array from a slice of an immutable byte array.
-- The offset and length are given in bytes.
--
-- This operation makes a copy of the specified slice, so it is safe to
-- use the immutable array afterward.
--
-- Note: The provided array should contain the full subrange
-- specified by the two Ints, but this is not checked.
thawByteArray :: PrimMonad m => ByteArray -> Int -> Int -> m (MutableByteArray (PrimState m))
-- | Execute the monadic action and freeze the resulting array.
--
--
-- runByteArray m = runST $ m >>= unsafeFreezeByteArray
--
runByteArray :: (forall s. () => ST s (MutableByteArray s)) -> ByteArray
createByteArray :: Int -> (forall s. () => MutableByteArray s -> ST s ()) -> ByteArray
-- | Convert a mutable byte array to an immutable one without copying. The
-- array should not be modified after the conversion.
unsafeFreezeByteArray :: PrimMonad m => MutableByteArray (PrimState m) -> m ByteArray
-- | Convert an immutable byte array to a mutable one without copying. The
-- original array should not be used after the conversion.
unsafeThawByteArray :: PrimMonad m => ByteArray -> m (MutableByteArray (PrimState m))
-- | Copy a slice of an immutable byte array to a mutable byte array.
--
-- Note: this function does not do bounds or overlap checking.
copyByteArray :: PrimMonad m => MutableByteArray (PrimState m) -> Int -> ByteArray -> Int -> Int -> m ()
-- | Copy a slice of a mutable byte array into another array. The two
-- slices may not overlap.
--
-- Note: this function does not do bounds or overlap checking.
copyMutableByteArray :: PrimMonad m => MutableByteArray (PrimState m) -> Int -> MutableByteArray (PrimState m) -> Int -> Int -> m ()
-- | Copy a slice of a byte array to an unmanaged pointer address. These
-- must not overlap. The offset and length are given in elements, not in
-- bytes.
--
-- Note: this function does not do bounds or overlap checking.
copyByteArrayToPtr :: (PrimMonad m, Prim a) => Ptr a -> ByteArray -> Int -> Int -> m ()
-- | Copy a slice of a mutable byte array to an unmanaged pointer address.
-- These must not overlap. The offset and length are given in elements,
-- not in bytes.
--
-- Note: this function does not do bounds or overlap checking.
copyMutableByteArrayToPtr :: (PrimMonad m, Prim a) => Ptr a -> MutableByteArray (PrimState m) -> Int -> Int -> m ()
-- | Copy a slice of a byte array to an unmanaged address. These must not
-- overlap.
--
-- Note: This function is just copyByteArrayToPtr where a
-- is Word8.
copyByteArrayToAddr :: PrimMonad m => Ptr Word8 -> ByteArray -> Int -> Int -> m ()
-- | Copy a slice of a mutable byte array to an unmanaged address. These
-- must not overlap.
--
-- Note: This function is just copyMutableByteArrayToPtr where
-- a is Word8.
copyMutableByteArrayToAddr :: PrimMonad m => Ptr Word8 -> MutableByteArray (PrimState m) -> Int -> Int -> m ()
-- | Copy from an unmanaged pointer address to a byte array. These must not
-- overlap. The offset and length are given in elements, not in bytes.
--
-- Note: this function does not do bounds or overlap checking.
copyPtrToMutableByteArray :: (PrimMonad m, Prim a) => MutableByteArray (PrimState m) -> Int -> Ptr a -> Int -> m ()
-- | Copy a slice of a mutable byte array into another, potentially
-- overlapping array.
moveByteArray :: PrimMonad m => MutableByteArray (PrimState m) -> Int -> MutableByteArray (PrimState m) -> Int -> Int -> m ()
-- | Fill a slice of a mutable byte array with a value. The offset and
-- length are given in elements of type a rather than in bytes.
--
-- Note: this function does not do bounds checking.
setByteArray :: (Prim a, PrimMonad m) => MutableByteArray (PrimState m) -> Int -> Int -> a -> m ()
-- | Fill a slice of a mutable byte array with a byte.
--
-- Note: this function does not do bounds checking.
fillByteArray :: PrimMonad m => MutableByteArray (PrimState m) -> Int -> Int -> Word8 -> m ()
-- | Return a newly allocated array with the specified subrange of the
-- provided array. The provided array should contain the full subrange
-- specified by the two Ints, but this is not checked.
cloneByteArray :: ByteArray -> Int -> Int -> ByteArray
-- | Return a newly allocated mutable array with the specified subrange of
-- the provided mutable array. The provided mutable array should contain
-- the full subrange specified by the two Ints, but this is not checked.
cloneMutableByteArray :: PrimMonad m => MutableByteArray (PrimState m) -> Int -> Int -> m (MutableByteArray (PrimState m))
-- | Size of the byte array in bytes.
sizeofByteArray :: ByteArray -> Int
-- | Size of the mutable byte array in bytes.
--
-- This function is deprecated and will be removed. Its behavior is
-- undefined if resizeMutableByteArray is ever called on the
-- mutable byte array given as the argument. Prefer
-- getSizeofMutableByteArray, which ensures correct sequencing in
-- the presence of resizing.
-- | Deprecated: use getSizeofMutableByteArray instead
sizeofMutableByteArray :: MutableByteArray s -> Int
-- | Get the size of a byte array in bytes. Unlike
-- sizeofMutableByteArray, this function ensures sequencing in the
-- presence of resizing.
getSizeofMutableByteArray :: PrimMonad m => MutableByteArray (PrimState m) -> m Int
-- | Check if the two arrays refer to the same memory block.
sameMutableByteArray :: MutableByteArray s -> MutableByteArray s -> Bool
-- | Check whether or not the byte array is pinned. Pinned byte arrays
-- cannot be moved by the garbage collector. It is safe to use
-- byteArrayContents on such byte arrays.
--
-- Caution: This function is only available when compiling with GHC 8.2
-- or newer.
isByteArrayPinned :: ByteArray -> Bool
-- | Check whether or not the mutable byte array is pinned.
--
-- Caution: This function is only available when compiling with GHC 8.2
-- or newer.
isMutableByteArrayPinned :: MutableByteArray s -> Bool
-- | Create a foreign pointer that points to the array's data. This
-- operation is only safe on pinned byte arrays. The array's data
-- is not garbage collected while references to the foreign pointer
-- exist. Writing to the array through the foreign pointer results in
-- undefined behavior.
byteArrayAsForeignPtr :: ByteArray -> ForeignPtr Word8
-- | Variant of byteArrayAsForeignPtr for mutable byte arrays.
-- Similarly, this is only safe on pinned mutable byte arrays.
-- This function differs from the variant for immutable arrays in that it
-- is safe to write to the array though the foreign pointer.
mutableByteArrayAsForeignPtr :: MutableByteArray RealWorld -> ForeignPtr Word8
-- | Yield a pointer to the array's data. This operation is only safe on
-- pinned byte arrays. Byte arrays allocated by
-- newPinnedByteArray and newAlignedPinnedByteArray are
-- guaranteed to be pinned. Byte arrays allocated by newByteArray
-- may or may not be pinned (use isByteArrayPinned to figure out).
--
-- Prefer withByteArrayContents, which ensures that the array is
-- not garbage collected while the pointer is being used.
byteArrayContents :: ByteArray -> Ptr Word8
-- | A composition of byteArrayContents and
-- keepAliveUnlifted. The callback function must not return the
-- pointer. The argument byte array must be pinned. See
-- byteArrayContents for an explanation of which byte arrays are
-- pinned.
--
-- Note: This could be implemented with keepAlive instead of
-- keepAliveUnlifted, but keepAlive here would cause GHC to
-- materialize the wrapper data constructor on the heap.
withByteArrayContents :: PrimBase m => ByteArray -> (Ptr Word8 -> m a) -> m a
-- | Yield a pointer to the array's data. This operation is only safe on
-- pinned byte arrays. See byteArrayContents for an
-- explanation of which byte arrays are pinned.
--
-- Prefer withByteArrayContents, which ensures that the array is
-- not garbage collected while the pointer is being used.
mutableByteArrayContents :: MutableByteArray s -> Ptr Word8
-- | A composition of mutableByteArrayContents and
-- keepAliveUnlifted. The callback function must not return the
-- pointer. The argument byte array must be pinned. See
-- byteArrayContents for an explanation of which byte arrays are
-- pinned.
withMutableByteArrayContents :: PrimBase m => MutableByteArray (PrimState m) -> (Ptr Word8 -> m a) -> m a
-- | Arrays of unboxed primitive types. The functions provided by this
-- module match the behavior of those provided by
-- Data.Primitive.ByteArray, and the underlying types and primops
-- that back them are the same. However, the type constructors
-- PrimArray and MutablePrimArray take one additional
-- argument compared to their respective counterparts ByteArray
-- and MutableByteArray. This argument is used to designate the
-- type of element in the array. Consequently, all functions in this
-- module accept length and indices in terms of elements, not bytes.
module Data.Primitive.PrimArray
-- | Arrays of unboxed elements. This accepts types like Double,
-- Char, Int and Word, as well as their fixed-length
-- variants (Word8, Word16, etc.). Since the elements are
-- unboxed, a PrimArray is strict in its elements. This differs
-- from the behavior of Array, which is lazy in its elements.
data PrimArray a
PrimArray :: ByteArray# -> PrimArray a
-- | Mutable primitive arrays associated with a primitive state token.
-- These can be written to and read from in a monadic context that
-- supports sequencing, such as IO or ST. Typically, a
-- mutable primitive array will be built and then converted to an
-- immutable primitive array using unsafeFreezePrimArray. However,
-- it is also acceptable to simply discard a mutable primitive array
-- since it lives in managed memory and will be garbage collected when no
-- longer referenced.
data MutablePrimArray s a
MutablePrimArray :: MutableByteArray# s -> MutablePrimArray s a
-- | Create a new mutable primitive array of the given length. The
-- underlying memory is left uninitialized.
--
-- Note: this function does not check if the input is
-- non-negative.
newPrimArray :: (PrimMonad m, Prim a) => Int -> m (MutablePrimArray (PrimState m) a)
-- | Create a pinned primitive array of the specified size (in
-- elements). The garbage collector is guaranteed not to move it. The
-- underlying memory is left uninitialized.
newPinnedPrimArray :: (PrimMonad m, Prim a) => Int -> m (MutablePrimArray (PrimState m) a)
-- | Create a pinned primitive array of the specified size (in
-- elements) and with the alignment given by its Prim instance.
-- The garbage collector is guaranteed not to move it. The underlying
-- memory is left uninitialized.
newAlignedPinnedPrimArray :: (PrimMonad m, Prim a) => Int -> m (MutablePrimArray (PrimState m) a)
-- | Resize a mutable primitive array. The new size is given in elements.
--
-- This will either resize the array in-place or, if not possible,
-- allocate the contents into a new, unpinned array and copy the original
-- array's contents.
--
-- To avoid undefined behaviour, the original MutablePrimArray
-- shall not be accessed anymore after a resizeMutablePrimArray
-- has been performed. Moreover, no reference to the old one should be
-- kept in order to allow garbage collection of the original
-- MutablePrimArray in case a new MutablePrimArray had to
-- be allocated.
resizeMutablePrimArray :: (PrimMonad m, Prim a) => MutablePrimArray (PrimState m) a -> Int -> m (MutablePrimArray (PrimState m) a)
-- | Shrink a mutable primitive array. The new size is given in elements.
-- It must be smaller than the old size. The array will be resized in
-- place.
shrinkMutablePrimArray :: (PrimMonad m, Prim a) => MutablePrimArray (PrimState m) a -> Int -> m ()
-- | Read a value from the array at the given index.
--
-- Note: this function does not do bounds checking.
readPrimArray :: (Prim a, PrimMonad m) => MutablePrimArray (PrimState m) a -> Int -> m a
-- | Write an element to the given index.
--
-- Note: this function does not do bounds checking.
writePrimArray :: (Prim a, PrimMonad m) => MutablePrimArray (PrimState m) a -> Int -> a -> m ()
-- | Read a primitive value from the primitive array.
--
-- Note: this function does not do bounds checking.
indexPrimArray :: Prim a => PrimArray a -> Int -> a
-- | Create an immutable copy of a slice of a primitive array. The offset
-- and length are given in elements.
--
-- This operation makes a copy of the specified section, so it is safe to
-- continue using the mutable array afterward.
--
-- Note: The provided array should contain the full subrange
-- specified by the two Ints, but this is not checked.
freezePrimArray :: (PrimMonad m, Prim a) => MutablePrimArray (PrimState m) a -> Int -> Int -> m (PrimArray a)
-- | Create a mutable primitive array from a slice of an immutable
-- primitive array. The offset and length are given in elements.
--
-- This operation makes a copy of the specified slice, so it is safe to
-- use the immutable array afterward.
--
-- Note: The provided array should contain the full subrange
-- specified by the two Ints, but this is not checked.
thawPrimArray :: (PrimMonad m, Prim a) => PrimArray a -> Int -> Int -> m (MutablePrimArray (PrimState m) a)
-- | Execute the monadic action and freeze the resulting array.
--
--
-- runPrimArray m = runST $ m >>= unsafeFreezePrimArray
--
runPrimArray :: (forall s. () => ST s (MutablePrimArray s a)) -> PrimArray a
-- | Create an uninitialized array of the given length, apply the function
-- to it, and freeze the result.
--
-- Note: this function does not check if the input is
-- non-negative.
--
-- @since FIXME
createPrimArray :: Prim a => Int -> (forall s. () => MutablePrimArray s a -> ST s ()) -> PrimArray a
-- | Convert a mutable primitive array to an immutable one without copying.
-- The array should not be modified after the conversion.
unsafeFreezePrimArray :: PrimMonad m => MutablePrimArray (PrimState m) a -> m (PrimArray a)
-- | Convert an immutable array to a mutable one without copying. The
-- original array should not be used after the conversion.
unsafeThawPrimArray :: PrimMonad m => PrimArray a -> m (MutablePrimArray (PrimState m) a)
-- | Copy part of an array into another mutable array.
--
-- Note: this function does not do bounds or overlap checking.
copyPrimArray :: (PrimMonad m, Prim a) => MutablePrimArray (PrimState m) a -> Int -> PrimArray a -> Int -> Int -> m ()
-- | Copy part of a mutable array into another mutable array. In the case
-- that the destination and source arrays are the same, the regions may
-- overlap.
--
-- Note: this function does not do bounds or overlap checking.
copyMutablePrimArray :: (PrimMonad m, Prim a) => MutablePrimArray (PrimState m) a -> Int -> MutablePrimArray (PrimState m) a -> Int -> Int -> m ()
-- | Copy a slice of an immutable primitive array to a pointer. The offset
-- and length are given in elements of type a. This function
-- assumes that the Prim instance of a agrees with the
-- Storable instance.
--
-- Note: this function does not do bounds or overlap checking.
copyPrimArrayToPtr :: (PrimMonad m, Prim a) => Ptr a -> PrimArray a -> Int -> Int -> m ()
-- | Copy a slice of a mutable primitive array to a pointer. The offset and
-- length are given in elements of type a. This function assumes
-- that the Prim instance of a agrees with the
-- Storable instance.
--
-- Note: this function does not do bounds or overlap checking.
copyMutablePrimArrayToPtr :: (PrimMonad m, Prim a) => Ptr a -> MutablePrimArray (PrimState m) a -> Int -> Int -> m ()
-- | Copy from a pointer to a mutable primitive array. The offset and
-- length are given in elements of type a. This function assumes
-- that the Prim instance of a agrees with the
-- Storable instance.
--
-- Note: this function does not do bounds or overlap checking.
copyPtrToMutablePrimArray :: (PrimMonad m, Prim a) => MutablePrimArray (PrimState m) a -> Int -> Ptr a -> Int -> m ()
-- | Return a newly allocated array with the specified subrange of the
-- provided array. The provided array should contain the full subrange
-- specified by the two Ints, but this is not checked.
clonePrimArray :: Prim a => PrimArray a -> Int -> Int -> PrimArray a
-- | Return a newly allocated mutable array with the specified subrange of
-- the provided mutable array. The provided mutable array should contain
-- the full subrange specified by the two Ints, but this is not checked.
cloneMutablePrimArray :: (PrimMonad m, Prim a) => MutablePrimArray (PrimState m) a -> Int -> Int -> m (MutablePrimArray (PrimState m) a)
-- | Fill a slice of a mutable primitive array with a value.
--
-- Note: this function does not do bounds checking.
setPrimArray :: (Prim a, PrimMonad m) => MutablePrimArray (PrimState m) a -> Int -> Int -> a -> m ()
-- | Check if the two arrays refer to the same memory block.
sameMutablePrimArray :: MutablePrimArray s a -> MutablePrimArray s a -> Bool
-- | Get the size of a mutable primitive array in elements. Unlike
-- sizeofMutablePrimArray, this function ensures sequencing in the
-- presence of resizing.
getSizeofMutablePrimArray :: (PrimMonad m, Prim a) => MutablePrimArray (PrimState m) a -> m Int
-- | Size of the mutable primitive array in elements. This function shall
-- not be used on primitive arrays that are an argument to or a result of
-- resizeMutablePrimArray or shrinkMutablePrimArray.
--
-- This function is deprecated and will be removed.
-- | Deprecated: use getSizeofMutablePrimArray instead
sizeofMutablePrimArray :: forall s a. Prim a => MutablePrimArray s a -> Int
-- | Get the size, in elements, of the primitive array.
sizeofPrimArray :: Prim a => PrimArray a -> Int
-- | Yield a pointer to the array's data. This operation is only safe on
-- pinned prim arrays allocated by newPinnedByteArray or
-- newAlignedPinnedByteArray.
primArrayContents :: PrimArray a -> Ptr a
-- | A composition of primArrayContents and
-- keepAliveUnlifted. The callback function must not return the
-- pointer. The argument array must be pinned. See
-- primArrayContents for an explanation of which primitive arrays
-- are pinned.
--
-- Note: This could be implemented with keepAlive instead of
-- keepAliveUnlifted, but keepAlive here would cause GHC to
-- materialize the wrapper data constructor on the heap.
withPrimArrayContents :: PrimBase m => PrimArray a -> (Ptr a -> m a) -> m a
-- | Yield a pointer to the array's data. This operation is only safe on
-- pinned byte arrays allocated by newPinnedByteArray or
-- newAlignedPinnedByteArray.
mutablePrimArrayContents :: MutablePrimArray s a -> Ptr a
-- | A composition of mutablePrimArrayContents and
-- keepAliveUnlifted. The callback function must not return the
-- pointer. The argument array must be pinned. See
-- primArrayContents for an explanation of which primitive arrays
-- are pinned.
withMutablePrimArrayContents :: PrimBase m => MutablePrimArray (PrimState m) a -> (Ptr a -> m a) -> m a
-- | Check whether or not the primitive array is pinned. Pinned primitive
-- arrays cannot be moved by the garbage collector. It is safe to use
-- primArrayContents on such arrays. This function is only
-- available when compiling with GHC 8.2 or newer.
isPrimArrayPinned :: PrimArray a -> Bool
-- | Check whether or not the mutable primitive array is pinned. This
-- function is only available when compiling with GHC 8.2 or newer.
isMutablePrimArrayPinned :: MutablePrimArray s a -> Bool
-- | Convert a PrimArray to a list.
primArrayToList :: Prim a => PrimArray a -> [a]
-- | Create a PrimArray from a list.
--
--
-- primArrayFromList vs = primArrayFromListN (length vs) vs
--
primArrayFromList :: Prim a => [a] -> PrimArray a
-- | Create a PrimArray from a list of a known length. If the length
-- of the list does not match the given length, this throws an exception.
primArrayFromListN :: Prim a => Int -> [a] -> PrimArray a
-- | Lazy right-associated fold over the elements of a PrimArray.
foldrPrimArray :: Prim a => (a -> b -> b) -> b -> PrimArray a -> b
-- | Strict right-associated fold over the elements of a PrimArray.
foldrPrimArray' :: Prim a => (a -> b -> b) -> b -> PrimArray a -> b
-- | Lazy left-associated fold over the elements of a PrimArray.
foldlPrimArray :: Prim a => (b -> a -> b) -> b -> PrimArray a -> b
-- | Strict left-associated fold over the elements of a PrimArray.
foldlPrimArray' :: Prim a => (b -> a -> b) -> b -> PrimArray a -> b
-- | Strict left-associated fold over the elements of a PrimArray.
foldlPrimArrayM' :: (Prim a, Monad m) => (b -> a -> m b) -> b -> PrimArray a -> m b
-- | Traverse the primitive array, discarding the results. There is no
-- PrimMonad variant of this function, since it would not provide
-- any performance benefit.
traversePrimArray_ :: (Applicative f, Prim a) => (a -> f b) -> PrimArray a -> f ()
-- | Traverse the primitive array with the indices, discarding the results.
-- There is no PrimMonad variant of this function, since it would
-- not provide any performance benefit.
itraversePrimArray_ :: (Applicative f, Prim a) => (Int -> a -> f b) -> PrimArray a -> f ()
-- | The empty PrimArray.
emptyPrimArray :: PrimArray a
-- | Map over the elements of a primitive array.
mapPrimArray :: (Prim a, Prim b) => (a -> b) -> PrimArray a -> PrimArray b
-- | Indexed map over the elements of a primitive array.
imapPrimArray :: (Prim a, Prim b) => (Int -> a -> b) -> PrimArray a -> PrimArray b
-- | Generate a primitive array.
generatePrimArray :: Prim a => Int -> (Int -> a) -> PrimArray a
-- | Create a primitive array by copying the element the given number of
-- times.
replicatePrimArray :: Prim a => Int -> a -> PrimArray a
-- | Filter elements of a primitive array according to a predicate.
filterPrimArray :: Prim a => (a -> Bool) -> PrimArray a -> PrimArray a
-- | Map over a primitive array, optionally discarding some elements. This
-- has the same behavior as Data.Maybe.mapMaybe.
mapMaybePrimArray :: (Prim a, Prim b) => (a -> Maybe b) -> PrimArray a -> PrimArray b
-- | Traverse a primitive array. The traversal performs all of the
-- applicative effects before forcing the resulting values and
-- writing them to the new primitive array. Consequently:
--
--
-- >>> traversePrimArray (\x -> print x $> bool x undefined (x == 2)) (fromList [1, 2, 3 :: Int])
-- 1
-- 2
-- 3
-- *** Exception: Prelude.undefined
--
--
-- The function traversePrimArrayP always outperforms this
-- function, but it requires a PrimMonad constraint, and it forces
-- the values as it performs the effects.
traversePrimArray :: (Applicative f, Prim a, Prim b) => (a -> f b) -> PrimArray a -> f (PrimArray b)
-- | Traverse a primitive array with the index of each element.
itraversePrimArray :: (Applicative f, Prim a, Prim b) => (Int -> a -> f b) -> PrimArray a -> f (PrimArray b)
-- | Generate a primitive array by evaluating the applicative generator
-- function at each index.
generatePrimArrayA :: (Applicative f, Prim a) => Int -> (Int -> f a) -> f (PrimArray a)
-- | Execute the applicative action the given number of times and store the
-- results in a PrimArray.
replicatePrimArrayA :: (Applicative f, Prim a) => Int -> f a -> f (PrimArray a)
-- | Filter the primitive array, keeping the elements for which the monadic
-- predicate evaluates true.
filterPrimArrayA :: (Applicative f, Prim a) => (a -> f Bool) -> PrimArray a -> f (PrimArray a)
-- | Map over the primitive array, keeping the elements for which the
-- applicative predicate provides a Just.
mapMaybePrimArrayA :: (Applicative f, Prim a, Prim b) => (a -> f (Maybe b)) -> PrimArray a -> f (PrimArray b)
-- | Traverse a primitive array. The traversal forces the resulting values
-- and writes them to the new primitive array as it performs the monadic
-- effects. Consequently:
--
--
-- >>> traversePrimArrayP (\x -> print x $> bool x undefined (x == 2)) (fromList [1, 2, 3 :: Int])
-- 1
-- 2
-- *** Exception: Prelude.undefined
--
--
-- In many situations, traversePrimArrayP can replace
-- traversePrimArray, changing the strictness characteristics of
-- the traversal but typically improving the performance. Consider the
-- following short-circuiting traversal:
--
--
-- incrPositiveA :: PrimArray Int -> Maybe (PrimArray Int)
-- incrPositiveA xs = traversePrimArray (\x -> bool Nothing (Just (x + 1)) (x > 0)) xs
--
--
-- This can be rewritten using traversePrimArrayP. To do this, we
-- must change the traversal context to MaybeT (ST s), which has
-- a PrimMonad instance:
--
--
-- incrPositiveB :: PrimArray Int -> Maybe (PrimArray Int)
-- incrPositiveB xs = runST $ runMaybeT $ traversePrimArrayP
-- (\x -> bool (MaybeT (return Nothing)) (MaybeT (return (Just (x + 1)))) (x > 0))
-- xs
--
--
-- Benchmarks demonstrate that the second implementation runs 150 times
-- faster than the first. It also results in fewer allocations.
traversePrimArrayP :: (PrimMonad m, Prim a, Prim b) => (a -> m b) -> PrimArray a -> m (PrimArray b)
-- | Traverse a primitive array with the indices. The traversal forces the
-- resulting values and writes them to the new primitive array as it
-- performs the monadic effects.
itraversePrimArrayP :: (Prim a, Prim b, PrimMonad m) => (Int -> a -> m b) -> PrimArray a -> m (PrimArray b)
-- | Generate a primitive array by evaluating the monadic generator
-- function at each index.
generatePrimArrayP :: (PrimMonad m, Prim a) => Int -> (Int -> m a) -> m (PrimArray a)
-- | Execute the monadic action the given number of times and store the
-- results in a primitive array.
replicatePrimArrayP :: (PrimMonad m, Prim a) => Int -> m a -> m (PrimArray a)
-- | Filter the primitive array, keeping the elements for which the monadic
-- predicate evaluates to true.
filterPrimArrayP :: (PrimMonad m, Prim a) => (a -> m Bool) -> PrimArray a -> m (PrimArray a)
-- | Map over the primitive array, keeping the elements for which the
-- monadic predicate provides a Just.
mapMaybePrimArrayP :: (PrimMonad m, Prim a, Prim b) => (a -> m (Maybe b)) -> PrimArray a -> m (PrimArray b)
instance GHC.Classes.Eq (Data.Primitive.PrimArray.MutablePrimArray s a)
instance (GHC.Classes.Eq a, Data.Primitive.Types.Prim a) => GHC.Classes.Eq (Data.Primitive.PrimArray.PrimArray a)
instance Data.Primitive.Types.Prim a => GHC.Internal.IsList.IsList (Data.Primitive.PrimArray.PrimArray a)
instance Language.Haskell.TH.Syntax.Lift (Data.Primitive.PrimArray.PrimArray a)
instance GHC.Internal.Base.Monoid (Data.Primitive.PrimArray.PrimArray a)
instance Control.DeepSeq.NFData (Data.Primitive.PrimArray.MutablePrimArray s a)
instance Control.DeepSeq.NFData (Data.Primitive.PrimArray.PrimArray a)
instance (GHC.Classes.Ord a, Data.Primitive.Types.Prim a) => GHC.Classes.Ord (Data.Primitive.PrimArray.PrimArray a)
instance GHC.Internal.Base.Semigroup (Data.Primitive.PrimArray.PrimArray a)
instance (GHC.Internal.Show.Show a, Data.Primitive.Types.Prim a) => GHC.Internal.Show.Show (Data.Primitive.PrimArray.PrimArray a)
-- | Primitive operations on machine addresses.
module Data.Primitive.Ptr
-- | A value of type Ptr a represents a pointer to an
-- object, or an array of objects, which may be marshalled to or from
-- Haskell values of type a.
--
-- The type a will often be an instance of class Storable
-- which provides the marshalling operations. However this is not
-- essential, and you can provide your own operations to access the
-- pointer. For example you might write small foreign functions to get or
-- set the fields of a C struct.
data Ptr a
Ptr :: Addr# -> Ptr a
-- | The constant nullPtr contains a distinguished value of
-- Ptr that is not associated with a valid memory location.
nullPtr :: Ptr a
-- | Offset a pointer by the given number of elements.
advancePtr :: Prim a => Ptr a -> Int -> Ptr a
-- | Subtract a pointer from another pointer. The result represents the
-- number of elements of type a that fit in the contiguous
-- memory range bounded by these two pointers.
subtractPtr :: Prim a => Ptr a -> Ptr a -> Int
-- | Read a value from a memory position given by a pointer and an offset.
-- The memory block the address refers to must be immutable. The offset
-- is in elements of type a rather than in bytes.
indexOffPtr :: Prim a => Ptr a -> Int -> a
-- | Read a value from a memory position given by an address and an offset.
-- The offset is in elements of type a rather than in bytes.
readOffPtr :: (Prim a, PrimMonad m) => Ptr a -> Int -> m a
-- | Write a value to a memory position given by an address and an offset.
-- The offset is in elements of type a rather than in bytes.
writeOffPtr :: (Prim a, PrimMonad m) => Ptr a -> Int -> a -> m ()
-- | Copy the given number of elements from the second Ptr to the
-- first. The areas may not overlap.
copyPtr :: (PrimMonad m, Prim a) => Ptr a -> Ptr a -> Int -> m ()
-- | Copy the given number of elements from the second Ptr to the
-- first. The areas may overlap.
movePtr :: (PrimMonad m, Prim a) => Ptr a -> Ptr a -> Int -> m ()
-- | Fill a memory block with the given value. The length is in elements of
-- type a rather than in bytes.
setPtr :: (Prim a, PrimMonad m) => Ptr a -> Int -> a -> m ()
-- | Copy from a pointer to a mutable primitive array. The offset and
-- length are given in elements of type a. This function assumes
-- that the Prim instance of a agrees with the
-- Storable instance.
--
-- Note: this function does not do bounds or overlap checking.
copyPtrToMutablePrimArray :: (PrimMonad m, Prim a) => MutablePrimArray (PrimState m) a -> Int -> Ptr a -> Int -> m ()
-- | Copy from an unmanaged pointer address to a byte array. These must not
-- overlap. The offset and length are given in elements, not in bytes.
--
-- Note: this function does not do bounds or overlap checking.
copyPtrToMutableByteArray :: (PrimMonad m, Prim a) => MutableByteArray (PrimState m) -> Int -> Ptr a -> Int -> m ()
-- | Reexports all primitive operations.
module Data.Primitive
-- | Variant of MutVar that has one less indirection for primitive
-- types. The difference is illustrated by comparing MutVar Int
-- and PrimVar Int:
--
--
-- - MutVar Int: MutVar# --> I#
-- - PrimVar Int: MutableByteArray#
--
--
-- This module is adapted from a module in Edward Kmett's
-- prim-ref library.
module Data.Primitive.PrimVar
-- | A PrimVar behaves like a single-element mutable primitive
-- array.
newtype PrimVar s a
PrimVar :: MutablePrimArray s a -> PrimVar s a
-- | Create a primitive reference.
newPrimVar :: (PrimMonad m, Prim a) => a -> m (PrimVar (PrimState m) a)
-- | Create a pinned primitive reference.
newPinnedPrimVar :: (PrimMonad m, Prim a) => a -> m (PrimVar (PrimState m) a)
-- | Create a pinned primitive reference with the appropriate alignment for
-- its contents.
newAlignedPinnedPrimVar :: (PrimMonad m, Prim a) => a -> m (PrimVar (PrimState m) a)
-- | Read a value from the PrimVar.
readPrimVar :: (PrimMonad m, Prim a) => PrimVar (PrimState m) a -> m a
-- | Write a value to the PrimVar.
writePrimVar :: (PrimMonad m, Prim a) => PrimVar (PrimState m) a -> a -> m ()
-- | Mutate the contents of a PrimVar.
modifyPrimVar :: (PrimMonad m, Prim a) => PrimVar (PrimState m) a -> (a -> a) -> m ()
-- | Yield a pointer to the data of a PrimVar. This operation is
-- only safe on pinned byte arrays allocated by newPinnedPrimVar
-- or newAlignedPinnedPrimVar.
primVarContents :: PrimVar s a -> Ptr a
-- | Convert a PrimVar to a one-elment MutablePrimArray.
primVarToMutablePrimArray :: PrimVar s a -> MutablePrimArray s a
-- | Given a primitive reference, the expected old value, and the new
-- value, perform an atomic compare and swap i.e. write the new value if
-- the current value matches the provided old value. Returns the value of
-- the element before the operation.
casInt :: PrimMonad m => PrimVar (PrimState m) Int -> Int -> Int -> m Int
-- | Given a reference, and a value to add, atomically add the value to the
-- element. Returns the value of the element before the operation.
fetchAddInt :: PrimMonad m => PrimVar (PrimState m) Int -> Int -> m Int
-- | Given a reference, and a value to subtract, atomically subtract the
-- value from the element. Returns the value of the element before the
-- operation.
fetchSubInt :: PrimMonad m => PrimVar (PrimState m) Int -> Int -> m Int
-- | Given a reference, and a value to bitwise and, atomically and the
-- value with the element. Returns the value of the element before the
-- operation.
fetchAndInt :: PrimMonad m => PrimVar (PrimState m) Int -> Int -> m Int
-- | Given a reference, and a value to bitwise nand, atomically nand the
-- value with the element. Returns the value of the element before the
-- operation.
fetchNandInt :: PrimMonad m => PrimVar (PrimState m) Int -> Int -> m Int
-- | Given a reference, and a value to bitwise or, atomically or the value
-- with the element. Returns the value of the element before the
-- operation.
fetchOrInt :: PrimMonad m => PrimVar (PrimState m) Int -> Int -> m Int
-- | Given a reference, and a value to bitwise xor, atomically xor the
-- value with the element. Returns the value of the element before the
-- operation.
fetchXorInt :: PrimMonad m => PrimVar (PrimState m) Int -> Int -> m Int
-- | Given a reference, atomically read an element.
atomicReadInt :: PrimMonad m => PrimVar (PrimState m) Int -> m Int
-- | Given a reference, atomically write an element.
atomicWriteInt :: PrimMonad m => PrimVar (PrimState m) Int -> Int -> m ()
instance GHC.Classes.Eq (Data.Primitive.PrimVar.PrimVar s a)