-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Primitive memory-related operations
--   
--   This package provides various primitive memory-related operations.
--   
--   Changes in version 0.5
--   
--   <ul>
--   <li>New in <a>Data.Primitive.MutVar</a>:
--   <tt>atomicModifyMutVar</tt></li>
--   <li>Efficient block fill operations: <tt>setByteArray</tt>,
--   <tt>setAddr</tt></li>
--   </ul>
@package primitive
@version 0.5


-- | Machine-dependent constants
module Data.Primitive.MachDeps
sIZEOF_CHAR :: Int
aLIGNMENT_WORD64 :: Int
sIZEOF_WORD64 :: Int
aLIGNMENT_INT64 :: Int
sIZEOF_INT64 :: Int
aLIGNMENT_WORD32 :: Int
sIZEOF_WORD32 :: Int
aLIGNMENT_INT32 :: Int
sIZEOF_INT32 :: Int
aLIGNMENT_WORD16 :: Int
sIZEOF_WORD16 :: Int
aLIGNMENT_INT16 :: Int
sIZEOF_INT16 :: Int
aLIGNMENT_WORD8 :: Int
sIZEOF_WORD8 :: Int
aLIGNMENT_INT8 :: Int
sIZEOF_INT8 :: Int
aLIGNMENT_STABLEPTR :: Int
sIZEOF_STABLEPTR :: Int
aLIGNMENT_FUNPTR :: Int
sIZEOF_FUNPTR :: Int
aLIGNMENT_PTR :: Int
sIZEOF_PTR :: Int
aLIGNMENT_FLOAT :: Int
sIZEOF_FLOAT :: Int
aLIGNMENT_DOUBLE :: Int
sIZEOF_DOUBLE :: Int
aLIGNMENT_WORD :: Int
sIZEOF_WORD :: Int
aLIGNMENT_INT :: Int
sIZEOF_INT :: Int
aLIGNMENT_CHAR :: Int
type Word64_# = Word64#
type Int64_# = Int64#


-- | Primitive state-transformer monads
module Control.Monad.Primitive

-- | Class of primitive state-transformer monads
class Monad m => PrimMonad m where type family PrimState m
primitive :: PrimMonad m => (State# (PrimState m) -> (# State# (PrimState m), a #)) -> m a
internal :: PrimMonad m => m a -> State# (PrimState m) -> (# State# (PrimState m), a #)

-- | <tt>RealWorld</tt> is deeply magical. It is <i>primitive</i>, but it
--   is not <i>unlifted</i> (hence <tt>ptrArg</tt>). We never manipulate
--   values of type <tt>RealWorld</tt>; it's only used in the type system,
--   to parameterise <tt>State#</tt>.
data RealWorld :: *

-- | Execute a primitive operation with no result
primitive_ :: PrimMonad m => (State# (PrimState m) -> State# (PrimState m)) -> m ()

-- | Convert a <a>PrimMonad</a> to another monad with the same state token.
primToPrim :: (PrimMonad m1, PrimMonad m2, PrimState m1 ~ PrimState m2) => m1 a -> m2 a

-- | Convert a <a>PrimMonad</a> with a <a>RealWorld</a> state token to
--   <a>IO</a>
primToIO :: (PrimMonad m, PrimState m ~ RealWorld) => m a -> IO a

-- | Convert a <a>PrimMonad</a> to <a>ST</a>
primToST :: PrimMonad m => m a -> ST (PrimState m) a

-- | Convert a <a>PrimMonad</a> to another monad with a possibly different
--   state token. This operation is highly unsafe!
unsafePrimToPrim :: (PrimMonad m1, PrimMonad m2) => m1 a -> m2 a

-- | Convert any <a>PrimMonad</a> to <a>IO</a>. This operation is highly
--   unsafe!
unsafePrimToIO :: PrimMonad m => m a -> IO a

-- | Convert any <a>PrimMonad</a> to <a>ST</a> with an arbitrary state
--   token. This operation is highly unsafe!
unsafePrimToST :: PrimMonad m => m a -> ST s a
unsafeInlinePrim :: PrimMonad m => m a -> a
unsafeInlineIO :: IO a -> a
unsafeInlineST :: ST s a -> a
touch :: PrimMonad m => a -> m ()
instance PrimMonad (ST s)
instance PrimMonad IO


-- | Basic types and classes for primitive array operations
module Data.Primitive.Types

-- | Class of types supporting primitive array operations
class Prim a
sizeOf# :: Prim a => a -> Int#
alignment# :: Prim a => a -> Int#
indexByteArray# :: Prim a => ByteArray# -> Int# -> a
readByteArray# :: Prim a => MutableByteArray# s -> Int# -> State# s -> (# State# s, a #)
writeByteArray# :: Prim a => MutableByteArray# s -> Int# -> a -> State# s -> State# s
setByteArray# :: Prim a => MutableByteArray# s -> Int# -> Int# -> a -> State# s -> State# s
indexOffAddr# :: Prim a => Addr# -> Int# -> a
readOffAddr# :: Prim a => Addr# -> Int# -> State# s -> (# State# s, a #)
writeOffAddr# :: Prim a => Addr# -> Int# -> a -> State# s -> State# s
setOffAddr# :: Prim a => Addr# -> Int# -> Int# -> a -> State# s -> State# s

-- | A machine address
data Addr
Addr :: Addr# -> Addr
instance Typeable Addr
instance Prim Addr
instance Prim Char
instance Prim Double
instance Prim Float
instance Prim Int64
instance Prim Int32
instance Prim Int16
instance Prim Int8
instance Prim Int
instance Prim Word64
instance Prim Word32
instance Prim Word16
instance Prim Word8
instance Prim Word
instance Data Addr
instance Ord Addr
instance Eq Addr


-- | Primitive boxed arrays
module Data.Primitive.Array

-- | Boxed arrays
data 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

-- | Create a new mutable array of the specified size and initialise all
--   elements with the given value.
newArray :: PrimMonad m => Int -> a -> m (MutableArray (PrimState m) a)

-- | Read a value from the array at the given index.
readArray :: PrimMonad m => MutableArray (PrimState m) a -> Int -> m a

-- | Write a value to the array at the given index.
writeArray :: PrimMonad m => MutableArray (PrimState m) a -> Int -> a -> m ()

-- | Read a value from the immutable array at the given index.
indexArray :: Array a -> Int -> a

-- | Monadically read a value from the immutable array at the given index.
--   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:
--   
--   <pre>
--   copy marr arr ... = do ...
--                          writeArray marr i (indexArray arr i) ...
--                          ...
--   </pre>
--   
--   But since primitive arrays are lazy, the calls to <a>indexArray</a>
--   will not be evaluated. Rather, <tt>marr</tt> will be filled with
--   thunks each of which would retain a reference to <tt>arr</tt>. This is
--   definitely not what we want!
--   
--   With <a>indexArrayM</a>, we can instead write
--   
--   <pre>
--   copy marr arr ... = do ...
--                          x &lt;- indexArrayM arr i
--                          writeArray marr i x
--                          ...
--   </pre>
--   
--   Now, indexing is executed immediately although the returned element is
--   still not evaluated.
indexArrayM :: Monad m => Array a -> Int -> m 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.
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
--   not be the same.
copyMutableArray :: PrimMonad m => MutableArray (PrimState m) a -> Int -> MutableArray (PrimState m) a -> Int -> Int -> m ()
instance Typeable1 Array
instance Typeable2 MutableArray
instance (Typeable s, Typeable a) => Data (MutableArray s a)
instance Typeable a => Data (Array a)


-- | Primitive operations on ByteArrays
module Data.Primitive.ByteArray

-- | Byte arrays
data ByteArray
ByteArray :: ByteArray# -> ByteArray

-- | Mutable byte arrays associated with a primitive state token
data MutableByteArray s
MutableByteArray :: (MutableByteArray# s) -> MutableByteArray s
data ByteArray# :: #
data MutableByteArray# (a :: *) :: * -> #

-- | Create a new mutable byte array of the specified size.
newByteArray :: PrimMonad m => Int -> m (MutableByteArray (PrimState m))

-- | Create a <i>pinned</i> byte array of the specified size. The garbage
--   collector is guaranteed not to move it.
newPinnedByteArray :: PrimMonad m => Int -> m (MutableByteArray (PrimState m))

-- | Create a <i>pinned</i> byte array of the specified size and with the
--   give alignment. The garbage collector is guaranteed not to move it.
newAlignedPinnedByteArray :: PrimMonad m => Int -> Int -> m (MutableByteArray (PrimState m))

-- | Read a primitive value from the byte array. The offset is given in
--   elements of type <tt>a</tt> rather than in bytes.
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 <tt>a</tt> rather than in bytes.
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 <tt>a</tt> rather than in bytes.
indexByteArray :: Prim a => ByteArray -> Int -> a

-- | 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.
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.
copyMutableByteArray :: PrimMonad m => MutableByteArray (PrimState m) -> Int -> MutableByteArray (PrimState m) -> Int -> 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 <tt>a</tt> rather than in bytes.
setByteArray :: (Prim a, PrimMonad m) => MutableByteArray (PrimState m) -> Int -> Int -> a -> m ()

-- | Fill a slice of a mutable byte array with a byte.
fillByteArray :: PrimMonad m => MutableByteArray (PrimState m) -> Int -> Int -> Word8 -> m ()

-- | Size of the byte array.
sizeofByteArray :: ByteArray -> Int

-- | Size of the mutable byte array.
sizeofMutableByteArray :: MutableByteArray s -> Int

-- | Check if the two arrays refer to the same memory block.
sameMutableByteArray :: MutableByteArray s -> MutableByteArray s -> Bool

-- | Yield a pointer to the array's data. This operation is only safe on
--   <i>pinned</i> byte arrays allocated by <a>newPinnedByteArray</a> or
--   <a>newAlignedPinnedByteArray</a>.
byteArrayContents :: ByteArray -> Addr

-- | Yield a pointer to the array's data. This operation is only safe on
--   <i>pinned</i> byte arrays allocated by <a>newPinnedByteArray</a> or
--   <a>newAlignedPinnedByteArray</a>.
mutableByteArrayContents :: MutableByteArray s -> Addr
instance Typeable ByteArray
instance Typeable1 MutableByteArray
instance Typeable s => Data (MutableByteArray s)
instance Data ByteArray


-- | Primitive operations on machine addresses
module Data.Primitive.Addr

-- | A machine address
data Addr
Addr :: Addr# -> Addr

-- | The null address
nullAddr :: Addr

-- | Offset an address by the given number of bytes
plusAddr :: Addr -> Int -> Addr

-- | Distance in bytes between two addresses. The result is only valid if
--   the difference fits in an <a>Int</a>.
minusAddr :: Addr -> Addr -> Int

-- | The remainder of the address and the integer.
remAddr :: Addr -> Int -> Int

-- | 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 <tt>a</tt> 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 <tt>a</tt> rather than in bytes.
readOffAddr :: (Prim a, PrimMonad m) => Addr -> Int -> m a

-- | Write a value to a memory position given by an address and an offset.
--   The offset is in elements of type <tt>a</tt> rather than in bytes.
writeOffAddr :: (Prim a, PrimMonad m) => Addr -> Int -> a -> m ()

-- | Copy the given number of bytes from the second <a>Addr</a> to the
--   first. The areas may not overlap.
copyAddr :: PrimMonad m => Addr -> Addr -> Int -> m ()

-- | Copy the given number of bytes from the second <a>Addr</a> to the
--   first. The areas may overlap.
moveAddr :: PrimMonad m => Addr -> Addr -> Int -> m ()

-- | Fill a memory block of with the given value. The length is in elements
--   of type <tt>a</tt> rather than in bytes.
setAddr :: (Prim a, PrimMonad m) => Addr -> Int -> a -> m ()


-- | Reexports all primitive operations
module Data.Primitive

-- | Size of values of type <tt>a</tt>. The argument is not used.
sizeOf :: Prim a => a -> Int

-- | Alignment of values of type <tt>a</tt>. The argument is not used.
alignment :: Prim a => a -> Int


-- | Primitive boxed mutable variables
module Data.Primitive.MutVar

-- | A <a>MutVar</a> 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 <a>MutVar</a> with the specified initial value
newMutVar :: PrimMonad m => a -> m (MutVar (PrimState m) a)

-- | Read the value of a <a>MutVar</a>
readMutVar :: PrimMonad m => MutVar (PrimState m) a -> m a

-- | Write a new value into a <a>MutVar</a>
writeMutVar :: PrimMonad m => MutVar (PrimState m) a -> a -> m ()

-- | Atomically mutate the contents of a <a>MutVar</a>
atomicModifyMutVar :: PrimMonad m => MutVar (PrimState m) a -> (a -> (a, b)) -> m b

-- | Mutate the contents of a <a>MutVar</a>
modifyMutVar :: PrimMonad m => MutVar (PrimState m) a -> (a -> a) -> m ()
instance Typeable2 MutVar
instance Eq (MutVar s a)