Moduleeffectful-core-2.7.1.2GHC2021

Effectful.Dispatch.Static.Primitive

Primitive API for statically dispatched effects.

This module exposes internal implementation details of the Eff monad. Most of the time functions from Effectful.Dispatch.Static are sufficient.

Warning: playing the so called "type tetris" with functions from this module is not enough. Their misuse might lead to data races or internal consistency check failures, so make sure you understand what you're doing.

2 types
11 values

Packageeffectful-core-2.7.1.2
Exports14
LanguageGHC2021
LicenceBSD-3-Clause
SourcePrimitive.hs

The environment

1 declaration

datadata Env (es :: [Effect])

A strict (WHNF), thread local, mutable, extensible record indexed by types of kind Effect.

Warning: the environment is a mutable data structure and cannot be simultaneously used from multiple threads under any circumstances.

In order to pass it to a different thread, you need to perform a deep copy with the cloneEnv function.

Offers very good performance characteristics for most often performed operations:

Extending: O(n), where n is the size of the effect stack.
Shrinking: O(1).
Indexing via (:>): O(1)
Modification of a specific element: O(1).
Getting a tail: O(1).
Cloning: O(N), where N is the size of the Storage.

Relinker

newtypenewtype Relinker (a :: Effect -> Type) (b :: Effect) where

A function for relinking Env objects stored in the handlers and/or making a deep copy of the representation of the effect when cloning the environment.

Constructors

Relinker :: (HasCallStack => (forall (es :: [Effect]). Env es -> IO (Env es)) -> a b -> IO (a b)) -> Relinker a b

valuedummyRelinker :: Relinker rep e

A dummy Relinker.

Representation of effects

familytype family EffectRep (d :: Dispatch) :: Effect -> Type

Internal representations of effects.

Instances2EffectRep

type EffectRep 'Dynamic = HandlerDefined in effectful-core-2.7.1.2 · Effectful.Internal.Monad · orphan
type EffectRep ('Static sideEffects) = StaticRepDefined in effectful-core-2.7.1.2 · Effectful.Internal.Monad · orphan

Extending and shrinking

valueconsEnv

:: HasCallStack
=> EffectRep (DispatchOf e) e
The representation of the effect.
-> Relinker (EffectRep (DispatchOf e)) e
-> Env es
-> IO (Env (e ': es))

Extend the environment with a new data type.

valueunconsEnv :: HasCallStack => Env (e ': es) -> IO ()

Shrink the environment by one data type.

The environment needs to come from consEnv, i.e. the intended usage is bracket (consEnv e f env) unconsEnv.

Note: after calling this function e from the input environment is no longer usable.

Data retrieval and update

valuegetEnv

:: (HasCallStack, e :> es)
=> Env es
The environment.
-> IO (EffectRep (DispatchOf e) e)

Extract a specific data type from the environment.

valueputEnv

:: (HasCallStack, e :> es)
=> Env es
The environment.
-> EffectRep (DispatchOf e) e
-> IO ()

Replace the data type in the environment with a new value (in place).

valuestateEnv

:: (HasCallStack, e :> es)
=> Env es
The environment.
-> (EffectRep (DispatchOf e) e -> (a, EffectRep (DispatchOf e) e))
-> IO a

Modify the data type in the environment and return a value (in place).

valuemodifyEnv

:: (HasCallStack, e :> es)
=> Env es
The environment.
-> (EffectRep (DispatchOf e) e -> EffectRep (DispatchOf e) e)
-> IO ()

Modify the data type in the environment (in place).

Utils

valueemptyEnv :: HasCallStack => IO (Env '[])

Create an empty environment.

valuecloneEnv :: HasCallStack => Env es -> IO (Env es)

Clone the environment to use it in a different thread.

valuesizeEnv :: Env es -> IO Int

Get the current size of the environment.

valuetailEnv :: Env (e ': es) -> IO (Env es)

Access the tail of the environment.