primitive-0.9.0.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 :: Type -> Type) where
  - type PrimState (m :: Type -> Type)
  - 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 :: Type -> Type) where
  - internal :: m a -> State# (PrimState m) -> (# State# (PrimState m), a #)
- class (PrimMonad m, s ~ PrimState m) => MonadPrim s (m :: Type -> Type)
- class (PrimBase m, MonadPrim s m) => MonadPrimBase s (m :: Type -> Type)
- 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 ()
- touchUnlifted :: forall m (a :: UnliftedType). PrimMonad m => a -> m ()
- keepAlive :: PrimBase m => a -> m r -> m r
- keepAliveUnlifted :: forall m (a :: UnliftedType) r. PrimBase m => a -> m r -> m r
- 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 :: Type -> Type) where #

Class of monads which can perform primitive state-transformer actions.

Associated Types

type PrimState (m :: Type -> Type) #

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 |
Instance details Defined in Control.Monad.Primitive type PrimState IO = RealWorld
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) |
Instance details Defined in Control.Monad.Primitive type PrimState (ST s) = 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) |
Instance details Defined in Control.Monad.Primitive type PrimState (ST s) = 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) |
Instance details Defined in Control.Monad.Primitive type PrimState (MaybeT m) = PrimState m
Methods primitive :: (State# (PrimState (MaybeT m)) -> (# State# (PrimState (MaybeT m)), a #)) -> MaybeT 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) |
Instance details Defined in Control.Monad.Primitive type PrimState (AccumT w m) = PrimState m
Methods primitive :: (State# (PrimState (AccumT w m)) -> (# State# (PrimState (AccumT w m)), a #)) -> AccumT w m a #
PrimMonad m => PrimMonad (ExceptT e m) # |
Instance details Defined in Control.Monad.Primitive Associated Types
type PrimState (ExceptT e m) |
Instance details Defined in Control.Monad.Primitive type PrimState (ExceptT e m) = PrimState m
Methods primitive :: (State# (PrimState (ExceptT e m)) -> (# State# (PrimState (ExceptT e m)), a #)) -> ExceptT e m a #
PrimMonad m => PrimMonad (IdentityT m) # |
Instance details Defined in Control.Monad.Primitive Associated Types
type PrimState (IdentityT m) |
Instance details Defined in Control.Monad.Primitive type PrimState (IdentityT m) = PrimState m
Methods primitive :: (State# (PrimState (IdentityT m)) -> (# State# (PrimState (IdentityT m)), a #)) -> IdentityT m a #
PrimMonad m => PrimMonad (ReaderT r m) # |
Instance details Defined in Control.Monad.Primitive Associated Types
type PrimState (ReaderT r m) |
Instance details Defined in Control.Monad.Primitive type PrimState (ReaderT r m) = PrimState m
Methods primitive :: (State# (PrimState (ReaderT r m)) -> (# State# (PrimState (ReaderT r m)), a #)) -> ReaderT r m a #
PrimMonad m => PrimMonad (SelectT r m) # |
Instance details Defined in Control.Monad.Primitive Associated Types
type PrimState (SelectT r m) |
Instance details Defined in Control.Monad.Primitive type PrimState (SelectT r m) = PrimState m
Methods primitive :: (State# (PrimState (SelectT r m)) -> (# State# (PrimState (SelectT r m)), a #)) -> SelectT r m a #
PrimMonad m => PrimMonad (StateT s m) # |
Instance details Defined in Control.Monad.Primitive Associated Types
type PrimState (StateT s m) |
Instance details Defined in Control.Monad.Primitive type PrimState (StateT s m) = PrimState 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) |
Instance details Defined in Control.Monad.Primitive type PrimState (StateT s m) = PrimState m
Methods primitive :: (State# (PrimState (StateT s m)) -> (# State# (PrimState (StateT s m)), a #)) -> StateT s m a #
(Monoid w, PrimMonad m) => PrimMonad (WriterT w m) # |
Instance details Defined in Control.Monad.Primitive Associated Types
type PrimState (WriterT w m) |
Instance details Defined in Control.Monad.Primitive type PrimState (WriterT w m) = PrimState 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) |
Instance details Defined in Control.Monad.Primitive type PrimState (WriterT w m) = PrimState 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) |
Instance details Defined in Control.Monad.Primitive type PrimState (WriterT w m) = PrimState m
Methods primitive :: (State# (PrimState (WriterT w m)) -> (# State# (PrimState (WriterT w m)), a #)) -> WriterT w 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) |
Instance details Defined in Control.Monad.Primitive type PrimState (ContT r m) = PrimState 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) |
Instance details Defined in Control.Monad.Primitive type PrimState (RWST r w s m) = PrimState 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) |
Instance details Defined in Control.Monad.Primitive type PrimState (RWST r w s m) = PrimState 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) |
Instance details Defined in Control.Monad.Primitive type PrimState (RWST r w s m) = PrimState 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 :: Type -> Type) 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 :: Type -> Type) #

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

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

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

touchUnlifted :: forall m (a :: UnliftedType). PrimMonad m => a -> m () #

Variant of `touch` that keeps a value of an unlifted type (e.g. `MutableByteArray#`) alive.

keepAlive #

Arguments

:: PrimBase m |
=> a | Value `x` to keep alive while computation `k` runs.
-> m r | Computation `k`
-> m r |

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

keepAliveUnlifted :: forall m (a :: UnliftedType) r. PrimBase m => a -> m r -> m r #

Variant of `keepAlive` in which the value kept alive is of an unlifted boxed type.

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