primitive-0.7.1.0: Primitive memory-related operations

Copyright | (c) Roman Leshchinskiy 2009
License | BSD-style
Maintainer | Roman Leshchinskiy <rl@cse.unsw.edu.au>
Portability | non-portable
Safe Haskell | None
Language | Haskell2010

Control.Monad.Primitive

Description

Primitive state-transformer monads

Synopsis

- class Monad m => PrimMonad m where
  - type PrimState m
  - primitive :: (State# (PrimState m) -> (# State# (PrimState m), a #)) -> m a
- data RealWorld
- primitive_ :: PrimMonad m => (State# (PrimState m) -> State# (PrimState m)) -> m ()
- class PrimMonad m => PrimBase m where
  - internal :: m a -> State# (PrimState m) -> (# State# (PrimState m), a #)
- class (PrimMonad m, s ~ PrimState m) => MonadPrim s m
- class (PrimBase m, MonadPrim s m) => MonadPrimBase s m
- liftPrim :: (PrimBase m1, PrimMonad m2, PrimState m1 ~ PrimState m2) => m1 a -> m2 a
- primToPrim :: (PrimBase m1, PrimMonad m2, PrimState m1 ~ PrimState m2) => m1 a -> m2 a
- primToIO :: (PrimBase m, PrimState m ~ RealWorld) => m a -> IO a
- primToST :: PrimBase m => m a -> ST (PrimState m) a
- ioToPrim :: (PrimMonad m, PrimState m ~ RealWorld) => IO a -> m a
- stToPrim :: PrimMonad m => ST (PrimState m) a -> m a
- unsafePrimToPrim :: (PrimBase m1, PrimMonad m2) => m1 a -> m2 a
- unsafePrimToIO :: PrimBase m => m a -> IO a
- unsafePrimToST :: PrimBase m => m a -> ST s a
- unsafeIOToPrim :: PrimMonad m => IO a -> m a
- unsafeSTToPrim :: PrimMonad m => ST s a -> m a
- unsafeInlinePrim :: PrimBase m => m a -> a
- unsafeInlineIO :: IO a -> a
- unsafeInlineST :: ST s a -> a
- touch :: PrimMonad m => a -> m ()
- 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 ()

# Documentation

class Monad m => PrimMonad m where #

Class of monads which can perform primitive state-transformer actions

Associated Types

type PrimState m #

State token type

Methods

primitive :: (State# (PrimState m) -> (# State# (PrimState m), a #)) -> m a #

Execute a primitive operation

#### Instances

Instances details

PrimMonad IO # |
Instance details Defined in Control.Monad.Primitive Associated Types type PrimState IO # Methods primitive :: (State# (PrimState IO) -> (# State# (PrimState IO), a #)) -> IO a #
PrimMonad (ST s) # |
Instance details Defined in Control.Monad.Primitive Associated Types type PrimState (ST s) # Methods primitive :: (State# (PrimState (ST s)) -> (# State# (PrimState (ST s)), a #)) -> ST s a #
PrimMonad (ST s) # |
Instance details Defined in Control.Monad.Primitive Associated Types type PrimState (ST s) # Methods primitive :: (State# (PrimState (ST s)) -> (# State# (PrimState (ST s)), a #)) -> ST s a #
PrimMonad m => PrimMonad (MaybeT m) # |
Instance details Defined in Control.Monad.Primitive Associated Types type PrimState (MaybeT m) # Methods primitive :: (State# (PrimState (MaybeT m)) -> (# State# (PrimState (MaybeT m)), a #)) -> MaybeT m a #
PrimMonad m => PrimMonad (ListT m) # |
Instance details Defined in Control.Monad.Primitive Associated Types type PrimState (ListT m) # Methods primitive :: (State# (PrimState (ListT m)) -> (# State# (PrimState (ListT m)), a #)) -> ListT m a #
(Monoid w, PrimMonad m) => PrimMonad (WriterT w m) # |
Instance details Defined in Control.Monad.Primitive Associated Types type PrimState (WriterT w m) # Methods primitive :: (State# (PrimState (WriterT w m)) -> (# State# (PrimState (WriterT w m)), a #)) -> WriterT w m a #
(Monoid w, PrimMonad m) => PrimMonad (AccumT w m) # | Since: 0.6.3.0
Instance details Defined in Control.Monad.Primitive Associated Types type PrimState (AccumT w m) # Methods primitive :: (State# (PrimState (AccumT w m)) -> (# State# (PrimState (AccumT w m)), a #)) -> AccumT w m a #
(Monoid w, PrimMonad m) => PrimMonad (WriterT w m) # |
Instance details Defined in Control.Monad.Primitive Associated Types type PrimState (WriterT w m) # Methods primitive :: (State# (PrimState (WriterT w m)) -> (# State# (PrimState (WriterT w m)), a #)) -> WriterT w m a #
(Monoid w, PrimMonad m) => PrimMonad (WriterT w m) # |
Instance details Defined in Control.Monad.Primitive Associated Types type PrimState (WriterT w m) # Methods primitive :: (State# (PrimState (WriterT w m)) -> (# State# (PrimState (WriterT w m)), a #)) -> WriterT w m a #
PrimMonad m => PrimMonad (StateT s m) # |
Instance details Defined in Control.Monad.Primitive Associated Types type PrimState (StateT s m) # Methods primitive :: (State# (PrimState (StateT s m)) -> (# State# (PrimState (StateT s m)), a #)) -> StateT s m a #
PrimMonad m => PrimMonad (StateT s m) # |
Instance details Defined in Control.Monad.Primitive Associated Types type PrimState (StateT s m) # Methods primitive :: (State# (PrimState (StateT s m)) -> (# State# (PrimState (StateT s m)), a #)) -> StateT s m a #
PrimMonad m => PrimMonad (SelectT r m) # |
Instance details Defined in Control.Monad.Primitive Associated Types type PrimState (SelectT r m) # Methods primitive :: (State# (PrimState (SelectT r m)) -> (# State# (PrimState (SelectT r m)), a #)) -> SelectT r m a #
PrimMonad m => PrimMonad (ReaderT r m) # |
Instance details Defined in Control.Monad.Primitive Associated Types type PrimState (ReaderT r m) # Methods primitive :: (State# (PrimState (ReaderT r m)) -> (# State# (PrimState (ReaderT r m)), a #)) -> ReaderT r m a #
PrimMonad m => PrimMonad (IdentityT m) # |
Instance details Defined in Control.Monad.Primitive Associated Types type PrimState (IdentityT m) # Methods primitive :: (State# (PrimState (IdentityT m)) -> (# State# (PrimState (IdentityT m)), a #)) -> IdentityT m a #
PrimMonad m => PrimMonad (ExceptT e m) # |
Instance details Defined in Control.Monad.Primitive Associated Types type PrimState (ExceptT e m) # Methods primitive :: (State# (PrimState (ExceptT e m)) -> (# State# (PrimState (ExceptT e m)), a #)) -> ExceptT e m a #
(Error e, PrimMonad m) => PrimMonad (ErrorT e m) # |
Instance details Defined in Control.Monad.Primitive Associated Types type PrimState (ErrorT e m) # Methods primitive :: (State# (PrimState (ErrorT e m)) -> (# State# (PrimState (ErrorT e m)), a #)) -> ErrorT e m a #
PrimMonad m => PrimMonad (ContT r m) # | Since: 0.6.3.0
Instance details Defined in Control.Monad.Primitive Associated Types type PrimState (ContT r m) # Methods primitive :: (State# (PrimState (ContT r m)) -> (# State# (PrimState (ContT r m)), a #)) -> ContT r m a #
(Monoid w, PrimMonad m) => PrimMonad (RWST r w s m) # |
Instance details Defined in Control.Monad.Primitive Associated Types type PrimState (RWST r w s m) # Methods primitive :: (State# (PrimState (RWST r w s m)) -> (# State# (PrimState (RWST r w s m)), a #)) -> RWST r w s m a #
(Monoid w, PrimMonad m) => PrimMonad (RWST r w s m) # |
Instance details Defined in Control.Monad.Primitive Associated Types type PrimState (RWST r w s m) # Methods primitive :: (State# (PrimState (RWST r w s m)) -> (# State# (PrimState (RWST r w s m)), a #)) -> RWST r w s m a #
(Monoid w, PrimMonad m) => PrimMonad (RWST r w s m) # |
Instance details Defined in Control.Monad.Primitive Associated Types type PrimState (RWST r w s m) # Methods primitive :: (State# (PrimState (RWST r w s m)) -> (# State# (PrimState (RWST r w s m)), a #)) -> RWST r w s m a #

data RealWorld #

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

primitive_ :: PrimMonad m => (State# (PrimState m) -> State# (PrimState m)) -> m () #

Execute a primitive operation with no result

class PrimMonad m => PrimBase m where #

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

Since: 0.6.0.0

Methods

internal :: m a -> State# (PrimState m) -> (# State# (PrimState m), a #) #

Expose the internal structure of the monad

#### Instances

Instances details

PrimBase IO # |
Instance details Defined in Control.Monad.Primitive Methods internal :: IO a -> State# (PrimState IO) -> (# State# (PrimState IO), a #) #
PrimBase (ST s) # |
Instance details Defined in Control.Monad.Primitive Methods internal :: ST s a -> State# (PrimState (ST s)) -> (# State# (PrimState (ST s)), a #) #
PrimBase (ST s) # |
Instance details Defined in Control.Monad.Primitive Methods internal :: ST s a -> State# (PrimState (ST s)) -> (# State# (PrimState (ST s)), a #) #
PrimBase m => PrimBase (IdentityT m) # | Since: 0.6.2.0
Instance details Defined in Control.Monad.Primitive Methods internal :: IdentityT m a -> State# (PrimState (IdentityT m)) -> (# State# (PrimState (IdentityT m)), a #) #

class (PrimMonad m, s ~ PrimState m) => MonadPrim s m #

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

#### Instances

Instances details

(PrimMonad m, s ~ PrimState m) => MonadPrim s m # |
Instance details Defined in Control.Monad.Primitive

class (PrimBase m, MonadPrim s m) => MonadPrimBase s m #

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

#### Instances

Instances details

(PrimBase m, MonadPrim s m) => MonadPrimBase s m # |
Instance details Defined in Control.Monad.Primitive

liftPrim :: (PrimBase m1, PrimMonad m2, PrimState m1 ~ PrimState m2) => m1 a -> m2 a #

Lifts a `PrimBase` into another `PrimMonad` with the same underlying state token type.

primToPrim :: (PrimBase m1, PrimMonad m2, PrimState m1 ~ PrimState m2) => m1 a -> m2 a #

Convert a `PrimBase` to another monad with the same state token.

primToIO :: (PrimBase m, PrimState m ~ RealWorld) => m a -> IO a #

Convert a `PrimBase` with a `RealWorld` state token to `IO`

primToST :: PrimBase m => m a -> ST (PrimState m) a #

Convert a `PrimBase` to `ST`

ioToPrim :: (PrimMonad m, PrimState m ~ RealWorld) => IO a -> m a #

Convert an `IO` action to a `PrimMonad`.

Since: 0.6.2.0

stToPrim :: PrimMonad m => ST (PrimState m) a -> m a #

Convert an `ST` action to a `PrimMonad`.

Since: 0.6.2.0

unsafePrimToPrim :: (PrimBase m1, PrimMonad m2) => m1 a -> m2 a #

Convert a `PrimBase` to another monad with a possibly different state token. This operation is highly unsafe!

unsafePrimToIO :: PrimBase m => m a -> IO a #

Convert any `PrimBase` to `IO`. This operation is highly unsafe!

unsafePrimToST :: PrimBase m => m a -> ST s a #

Convert any `PrimBase` to `ST` with an arbitrary state token. This operation is highly unsafe!

unsafeIOToPrim :: PrimMonad m => IO a -> m a #

Convert an `IO` action to any `PrimMonad`. This operation is highly unsafe!

Since: 0.6.2.0

unsafeSTToPrim :: PrimMonad m => ST s a -> m a #

Convert an `ST` action with an arbitrary state token to any `PrimMonad`. This operation is highly unsafe!

Since: 0.6.2.0

unsafeInlinePrim :: PrimBase m => m a -> a #

See `unsafeInlineIO`. This function is not recommended for the same reasons.

unsafeInlineIO :: IO 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.

unsafeInlineST :: ST s a -> a #

See `unsafeInlineIO`. This function is not recommended for the same reasons. Prefer `runST` when `s` is free.

touch :: PrimMonad m => a -> m () #

evalPrim :: forall a m. PrimMonad m => a -> m a #

Create an action to force a value; generalizes `evaluate`

Since: 0.6.2.0

unsafeInterleave :: PrimBase m => m a -> m a #

unsafeDupableInterleave :: PrimBase m => m a -> m a #

noDuplicate :: PrimMonad m => m () #