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 memory corruption or segmentation faults, so make sure you understand what you're doing.

The environment

data Env (es :: [Effect])

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

Supports forking, i.e. introduction of local branches for encapsulation of effects specific to effect handlers.

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

Offers very good performance characteristics for most often performed operations:

• Extending: O(1) (amortized).
• Shrinking: O(1).
• Indexing via (:>): O(1)
• Modification of a specific element: O(1).
• Forking: O(n), where n is the size of the effect stack.
• Cloning: O(N + Σ(n_i)), where N is the size of the Storage, while i ranges over handlers of dynamically dispatched effects in the Storage and n_i is the size of the effect stack of i-th handler.

Relinker

newtype Relinker :: (Effect -> Type) -> Effect -> Type 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 :: ((forall es. Env es -> IO (Env es)) -> rep e -> IO (rep e)) -> Relinker rep e

dummyRelinker :: Relinker rep e

A dummy Relinker.

Representation of effects

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

Internal representations of effects.

Instances

type EffectRep 'Dynamic

Defined in Effectful.Internal.Monad

type EffectRep 'Dynamic = Handler

type EffectRep ('Static sideEffects)

Defined in Effectful.Internal.Monad

type EffectRep ('Static sideEffects) = StaticRep

Extending and shrinking

consEnv

Arguments

:: 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 (in place).

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

Shrink the environment by one data type (in place).

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

Data retrieval and update

getEnv

Arguments

:: forall e es. e :> es

=> Env es

The environment.

-> IO (EffectRep (DispatchOf e) e)

Extract a specific data type from the environment.

putEnv

Arguments

:: forall e es. e :> es

=> Env es

The environment.

-> EffectRep (DispatchOf e) e

-> IO ()

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

stateEnv

Arguments

:: forall e es a. e :> es

=> Env es

The environment.

-> (EffectRep (DispatchOf e) e -> (a, EffectRep (DispatchOf e) e))

-> IO a

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

modifyEnv

Arguments

:: forall e es. 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

emptyEnv :: IO (Env '[])

Create an empty environment.

cloneEnv :: Env es -> IO (Env es)

Clone the environment to use it in a different thread.

forkEnv :: Env es -> IO (Env es)

Create a fork of the environment.

Forked environment can be updated independently of the original one within the same thread.

sizeEnv :: Env es -> IO Int

Get the current size of the environment.

checkSizeEnv :: Env es -> IO ()

Check that the size of the environment is internally consistent.

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

Access the tail of the environment.