libghc-primitive-doc 0.6.1.0-4 / usr / share / doc / libghc-primitive-doc / html / primitive.txt

-- 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.6.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_# = Word#
type Int64_# = Int#


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

-- | Class of monads which can perform primitive state-transformer actions
class Monad m => PrimMonad m where type PrimState m where {
    type family PrimState m;
}

-- | Execute a primitive operation
primitive :: PrimMonad m => (State# (PrimState m) -> (# State# (PrimState m), a #)) -> 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 ()

-- | Class of primitive monads for state-transformer actions.
--   
--   Unlike <a>PrimMonad</a>, this typeclass requires that the
--   <tt>Monad</tt> be fully expressed as a state transformer, therefore
--   disallowing other monad transformers on top of the base <tt>IO</tt> or
--   <tt>ST</tt>.
class PrimMonad m => PrimBase m

-- | Expose the internal structure of the monad
internal :: PrimBase m => m a -> State# (PrimState m) -> (# State# (PrimState m), a #)

-- | Lifts a <a>PrimBase</a> into another <a>PrimMonad</a> with the same
--   underlying state token type.
liftPrim :: (PrimBase m1, PrimMonad m2, PrimState m1 ~ PrimState m2) => m1 a -> m2 a

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

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

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

-- | Convert a <a>PrimBase</a> 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 <a>PrimBase</a> to <a>IO</a>. This operation is highly
--   unsafe!
unsafePrimToIO :: PrimBase m => m a -> IO a

-- | Convert any <a>PrimBase</a> to <a>ST</a> with an arbitrary state
--   token. This operation is highly unsafe!
unsafePrimToST :: PrimBase m => m a -> ST s a
unsafeInlinePrim :: PrimBase m => m a -> a
unsafeInlineIO :: IO a -> a
unsafeInlineST :: ST s a -> a
touch :: PrimMonad m => a -> m ()
instance Control.Monad.Primitive.PrimMonad GHC.Types.IO
instance Control.Monad.Primitive.PrimBase 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.List.ListT m)
instance Control.Monad.Primitive.PrimMonad m => Control.Monad.Primitive.PrimMonad (Control.Monad.Trans.Maybe.MaybeT m)
instance (Control.Monad.Trans.Error.Error e, Control.Monad.Primitive.PrimMonad m) => Control.Monad.Primitive.PrimMonad (Control.Monad.Trans.Error.ErrorT e m)
instance Control.Monad.Primitive.PrimMonad m => Control.Monad.Primitive.PrimMonad (Control.Monad.Trans.Reader.ReaderT r m)
instance Control.Monad.Primitive.PrimMonad m => Control.Monad.Primitive.PrimMonad (Control.Monad.Trans.State.Lazy.StateT s m)
instance (GHC.Base.Monoid w, Control.Monad.Primitive.PrimMonad m) => Control.Monad.Primitive.PrimMonad (Control.Monad.Trans.Writer.Lazy.WriterT w m)
instance (GHC.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.Except.ExceptT e m)
instance Control.Monad.Primitive.PrimMonad m => Control.Monad.Primitive.PrimMonad (Control.Monad.Trans.State.Strict.StateT s m)
instance (GHC.Base.Monoid w, Control.Monad.Primitive.PrimMonad m) => Control.Monad.Primitive.PrimMonad (Control.Monad.Trans.Writer.Strict.WriterT w m)
instance (GHC.Base.Monoid w, Control.Monad.Primitive.PrimMonad m) => Control.Monad.Primitive.PrimMonad (Control.Monad.Trans.RWS.Strict.RWST r w s m)
instance Control.Monad.Primitive.PrimMonad (GHC.ST.ST s)
instance Control.Monad.Primitive.PrimBase (GHC.ST.ST s)


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

-- | Class of types supporting primitive array operations
class Prim a

-- | 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#

-- | Read a value from the array. The offset is in elements of type
--   <tt>a</tt> rather than in bytes.
indexByteArray# :: Prim a => ByteArray# -> Int# -> a

-- | Read a value from the mutable array. The offset is in elements of type
--   <tt>a</tt> 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
--   <tt>a</tt> 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 <tt>a</tt> 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 <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 => 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 <tt>a</tt> 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 <tt>a</tt> rather than in
--   bytes.
setOffAddr# :: Prim a => Addr# -> Int# -> Int# -> a -> State# s -> State# s

-- | A machine address
data Addr
Addr :: Addr# -> Addr
instance GHC.Classes.Eq Data.Primitive.Types.Addr
instance GHC.Classes.Ord Data.Primitive.Types.Addr
instance Data.Data.Data Data.Primitive.Types.Addr
instance Data.Primitive.Types.Prim GHC.Types.Word
instance Data.Primitive.Types.Prim GHC.Word.Word8
instance Data.Primitive.Types.Prim GHC.Word.Word16
instance Data.Primitive.Types.Prim GHC.Word.Word32
instance Data.Primitive.Types.Prim GHC.Word.Word64
instance Data.Primitive.Types.Prim GHC.Types.Int
instance Data.Primitive.Types.Prim GHC.Int.Int8
instance Data.Primitive.Types.Prim GHC.Int.Int16
instance Data.Primitive.Types.Prim GHC.Int.Int32
instance Data.Primitive.Types.Prim GHC.Int.Int64
instance Data.Primitive.Types.Prim GHC.Types.Float
instance Data.Primitive.Types.Prim GHC.Types.Double
instance Data.Primitive.Types.Prim GHC.Types.Char
instance Data.Primitive.Types.Prim Data.Primitive.Types.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 ()

-- | 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.
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.
cloneMutableArray :: PrimMonad m => MutableArray (PrimState m) a -> Int -> Int -> m (MutableArray (PrimState m) a)
instance Data.Typeable.Internal.Typeable a => Data.Data.Data (Data.Primitive.Array.Array a)
instance (Data.Typeable.Internal.Typeable s, Data.Typeable.Internal.Typeable a) => Data.Data.Data (Data.Primitive.Array.MutableArray s 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 Data.Data.Data Data.Primitive.ByteArray.ByteArray
instance Data.Typeable.Internal.Typeable s => Data.Data.Data (Data.Primitive.ByteArray.MutableByteArray s)


-- | 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
infixl 6 `plusAddr`

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

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

-- | 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

-- | Strict version of <a>atomicModifyMutVar</a>. This forces both the
--   value stored in the <a>MutVar</a> as well as the value returned.
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 ()

-- | Strict version of <a>modifyMutVar</a>
modifyMutVar' :: PrimMonad m => MutVar (PrimState m) a -> (a -> a) -> m ()
instance GHC.Classes.Eq (Data.Primitive.MutVar.MutVar s a)