Control.Lens.Mutable.Types

Documentation

data PrimOpGroup

GHC implements different primitive operations, some of which cannot be mixed together and some of which can only be run in certain contexts. In particular, STM-related primops cannot be run directly in the IO monad. However, this restriction is not represented at the bottom layer of the IO runtime which we need to wrap around and expose to users.

This data structure is our ad-hoc attempt to group together "compatible" primops so that only lens representing compatible references can be composed together, avoiding deadly segfaults.

See https://gitlab.haskell.org/ghc/ghc/blob/master/compiler/prelude/primops.txt.pp

See also https://github.com/haskell/primitive/issues/43#issuecomment-613771394

Constructors

OpST

OpMVar

OpSTM

Instances

Bounded PrimOpGroup

Defined in Control.Lens.Mutable.Types

Methods

minBound :: PrimOpGroup

maxBound :: PrimOpGroup

Enum PrimOpGroup

Defined in Control.Lens.Mutable.Types

Methods

succ :: PrimOpGroup -> PrimOpGroup

pred :: PrimOpGroup -> PrimOpGroup

toEnum :: Int -> PrimOpGroup

fromEnum :: PrimOpGroup -> Int

enumFrom :: PrimOpGroup -> [PrimOpGroup]

enumFromThen :: PrimOpGroup -> PrimOpGroup -> [PrimOpGroup]

enumFromTo :: PrimOpGroup -> PrimOpGroup -> [PrimOpGroup]

enumFromThenTo :: PrimOpGroup -> PrimOpGroup -> PrimOpGroup -> [PrimOpGroup]

Eq PrimOpGroup

Defined in Control.Lens.Mutable.Types

Methods

(==) :: PrimOpGroup -> PrimOpGroup -> Bool

(/=) :: PrimOpGroup -> PrimOpGroup -> Bool

Ord PrimOpGroup

Defined in Control.Lens.Mutable.Types

Methods

compare :: PrimOpGroup -> PrimOpGroup -> Ordering

(<) :: PrimOpGroup -> PrimOpGroup -> Bool

(<=) :: PrimOpGroup -> PrimOpGroup -> Bool

(>) :: PrimOpGroup -> PrimOpGroup -> Bool

(>=) :: PrimOpGroup -> PrimOpGroup -> Bool

max :: PrimOpGroup -> PrimOpGroup -> PrimOpGroup

min :: PrimOpGroup -> PrimOpGroup -> PrimOpGroup

Read PrimOpGroup

Defined in Control.Lens.Mutable.Types

Methods

readsPrec :: Int -> ReadS PrimOpGroup

readList :: ReadS [PrimOpGroup]

readPrec :: ReadPrec PrimOpGroup

readListPrec :: ReadPrec [PrimOpGroup]

Show PrimOpGroup

Defined in Control.Lens.Mutable.Types

Methods

showsPrec :: Int -> PrimOpGroup -> ShowS

show :: PrimOpGroup -> String

showList :: [PrimOpGroup] -> ShowS

Generic PrimOpGroup

Defined in Control.Lens.Mutable.Types

Associated Types

type Rep PrimOpGroup :: Type -> Type

Methods

from :: PrimOpGroup -> Rep PrimOpGroup x

to :: Rep PrimOpGroup x -> PrimOpGroup

type Rep PrimOpGroup

Defined in Control.Lens.Mutable.Types

type Rep PrimOpGroup = D1 (MetaData "PrimOpGroup" "Control.Lens.Mutable.Types" "mutable-lens-0.4.0.0-F523ZU2qZxrApB6mfDtKDA" False) (C1 (MetaCons "OpST" PrefixI False) (U1 :: Type -> Type) :+: (C1 (MetaCons "OpMVar" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "OpSTM" PrefixI False) (U1 :: Type -> Type)))

data S (p :: PrimOpGroup) s

Lifted State#. This is needed to interoperate lifted ("normal") types and unlifted types (such as primitives), but it also gives us the chance to restrict composition based on PrimOpGroup which sadly isn't done in the unlifted internal representation (though it could be).

Constructors

S (State# s)

Instances

Allocable (S OpST RealWorld) a IORef

Defined in Control.Lens.Mutable.Internal

Methods

alloc :: a -> S OpST RealWorld -> (IORef a, S OpST RealWorld)

free :: IORef a -> S OpST RealWorld -> (a, S OpST RealWorld)

isValid :: IORef a -> S OpST RealWorld -> (Bool, S OpST RealWorld)

Allocable (S OpMVar RealWorld) a MVar

Defined in Control.Lens.Mutable.Internal

Methods

alloc :: a -> S OpMVar RealWorld -> (MVar a, S OpMVar RealWorld)

free :: MVar a -> S OpMVar RealWorld -> (a, S OpMVar RealWorld)

isValid :: MVar a -> S OpMVar RealWorld -> (Bool, S OpMVar RealWorld)

Allocable (S OpSTM RealWorld) a TMVar

Defined in Control.Lens.Mutable.Internal

Methods

alloc :: a -> S OpSTM RealWorld -> (TMVar a, S OpSTM RealWorld)

free :: TMVar a -> S OpSTM RealWorld -> (a, S OpSTM RealWorld)

isValid :: TMVar a -> S OpSTM RealWorld -> (Bool, S OpSTM RealWorld)

Allocable (S OpSTM RealWorld) a TVar

Defined in Control.Lens.Mutable.Internal

Methods

alloc :: a -> S OpSTM RealWorld -> (TVar a, S OpSTM RealWorld)

free :: TVar a -> S OpSTM RealWorld -> (a, S OpSTM RealWorld)

isValid :: TVar a -> S OpSTM RealWorld -> (Bool, S OpSTM RealWorld)

AsLens (S OpST RealWorld) a IORef

Defined in Control.Lens.Mutable.Internal

Methods

asLens :: IORef a -> Lens' (S OpST RealWorld) a

AsLens (S OpMVar RealWorld) a MVar

View a MVar a as a SLens 'OpST RealWorld a.

Note: when this is eventually run in IO, the action will block the thread until there is a value present, as per the semantics of takeMVar#. It will then put a value into the MVar, which will block the thread if the value is absent. GHC doesn't give atomicity guarantees for MVar so it's possible this does happen, e.g. if another producer managed to "get in there" during the intervening period between the two operations. Unfortunately GHC does not provide an atomic modifyMVar function or primop.

If you don't want to deal with this, don't use an MVar, use a TMVar.

Defined in Control.Lens.Mutable.Internal

Methods

asLens :: MVar a -> Lens' (S OpMVar RealWorld) a

AsLens (S OpSTM RealWorld) a TMVar

Defined in Control.Lens.Mutable.Internal

Methods

asLens :: TMVar a -> Lens' (S OpSTM RealWorld) a

AsLens (S OpSTM RealWorld) a TVar

Defined in Control.Lens.Mutable.Internal

Methods

asLens :: TVar a -> Lens' (S OpSTM RealWorld) a

Allocable (S OpST s) a (STRef s)

Defined in Control.Lens.Mutable.Internal

Methods

alloc :: a -> S OpST s -> (STRef s a, S OpST s)

free :: STRef s a -> S OpST s -> (a, S OpST s)

isValid :: STRef s a -> S OpST s -> (Bool, S OpST s)

Allocable (S OpST s) a (MutVar s)

Defined in Control.Lens.Mutable.Internal

Methods

alloc :: a -> S OpST s -> (MutVar s a, S OpST s)

free :: MutVar s a -> S OpST s -> (a, S OpST s)

isValid :: MutVar s a -> S OpST s -> (Bool, S OpST s)

AsLens (S OpST s) a (STRef s)

Defined in Control.Lens.Mutable.Internal

Methods

asLens :: STRef s a -> Lens' (S OpST s) a

AsLens (S OpST s) a (MutVar s)

Defined in Control.Lens.Mutable.Internal

Methods

asLens :: MutVar s a -> Lens' (S OpST s) a

type LST p s r = S p s -> (r, S p s)

A lifted primitive state-transformer that interoperates with lens.

Specifically, this is a bare (unwrapped in StateT) state transition on a lifted ("normal") state type.

To obtain one of these, you may apply a SLens p s a to a bare state transition, i.e. a function of type (a -> (r, a)).

class FromLST p s m where

Convert an LST p to some context m.

This is similar to PrimMonad from the primitives package except our extra p type-param helps us avoid accidentally mixing incompatible primops.

Methods

stToM :: LST p s r -> m r

Instances

(PrimMonad m, s ~ PrimState m) => FromLST OpST s m

Defined in Control.Lens.Mutable.Types

Methods

stToM :: LST OpST s r -> m r

FromLST OpMVar RealWorld IO

Defined in Control.Lens.Mutable.Types

Methods

stToM :: LST OpMVar RealWorld r -> IO r

FromLST OpSTM RealWorld STM

Defined in Control.Lens.Mutable.Types

Methods

stToM :: LST OpSTM RealWorld r -> STM r

class FromLST p s m => IsoLST p s m where

Convert an LST p to and from some context m.

This is similar to PrimBase from the primitives package except our extra p type-param helps us avoid accidentally mixing incompatible primops.

Methods

mToST :: m r -> LST p s r

Instances

(PrimBase m, s ~ PrimState m) => IsoLST OpST s m

Defined in Control.Lens.Mutable.Types

Methods

mToST :: m r -> LST OpST s r

IsoLST OpMVar RealWorld IO

Defined in Control.Lens.Mutable.Types

Methods

mToST :: IO r -> LST OpMVar RealWorld r

IsoLST OpSTM RealWorld STM

Defined in Control.Lens.Mutable.Types

Methods

mToST :: STM r -> LST OpSTM RealWorld r

type MonadLST p s m = (FromLST p s m, Monad m)

Convert an 'LST p from some monadic action m.

type SLens p s a = Lens' (S p s) a

Representation of a mutable reference as a Lens'.

When the lens functor type-param is (,) r, then the output transition function is of type LST s r. To use it as a monadic action e.g. to run it, you'll need to first convert it using stToM.

Again, in principle this ought not to be necessary, but the Haskell runtime forces us to do this due to historical design decisions to hide necessary details that seemed appropriate to hide at the time.

type ASLens p s a = ALens' (S p s) a

Representation of a mutable reference as a ALens'.

This type is useful if you need to store a lens in a container. To recover the original type, pass it through cloneLens.

Convenience functions

runSLens :: FromLST p s m => LensLike' ((,) r) (S p s) a -> (a -> (r, a)) -> m r

Run a bare state transition on a lens in the monad for p.

The lens may be an SLens p or any compositions of it with other optics, including prisms and so forth.

runASLens :: FromLST p s m => ALens' (S p s) a -> (a -> (r, a)) -> m r

Run a bare state transition on an ALens' in the monad for p.

stateRead :: a -> (a, a)

A bare state transition representing a read operation.

stateWrite :: b -> a -> ((), b)

A bare state transition representing a write operation.

stateWrite b can be passed to runSLens to write b to the reference.

stateModify :: (a -> b) -> a -> ((), b)

A bare state transition representing a modify/map operation.

stateModify f can be passed to runSLens to apply f to the reference.