Data.StateVar

stable

State variables are references in the IO monad, like IORefs or parts of the OpenGL state. Note that state variables are not neccessarily writable or readable, they may come in read-only or write-only flavours, too. As a very simple example for a state variable, consider an explicitly allocated memory buffer. This buffer could easily be converted into a StateVar:

makeStateVarFromPtr :: Storable a => Ptr a -> StateVar a
makeStateVarFromPtr p = makeStateVar (peek p) (poke p)

The example below puts 11 into a state variable (i.e. into the buffer), increments the contents of the state variable by 22, and finally prints the resulting content:

  do p <- malloc :: IO (Ptr Int)
     let v = makeStateVarFromPtr p
     v $= 11
     v $~ (+ 22)
     x <- get v
     print x

However, Ptr can be used directly through the same API:

  do p <- malloc :: IO (Ptr Int)
     p $= 11
     p $~ (+ 22)
     x <- get p
     print x

IORefs are state variables, too, so an example with them looks extremely similiar:

  do v <- newIORef (0 :: Int)
     v $= 11
     v $~ (+ 22)
     x <- get v
     print x

4 generation diagnostics

unattached documentation comment at 98:1
unattached documentation comment at 170:1
unattached documentation comment at 210:1
unattached documentation comment at 271:1

Readable State Variables

`class HasGetter t a`

This is the class of all readable state variables.

`get :: MonadIO m => t -> m a`

`type GettableStateVar = IO`

A concrete implementation of a read-only state variable is simply an IO action to read the value.

`makeGettableStateVar :: IO a -> GettableStateVar a`

Construct a GettableStateVar from an IO action.

getter

Writable State Variables

`class HasSetter t a`

This is the class of all writable state variables.

`($=) :: MonadIO m => t -> a -> m ()`

Write a new value into a state variable.

`($=!) :: (HasSetter t a, MonadIO m) => t -> a -> m ()`

This is a variant of $= which is strict in the value to be set.

`newtype SettableStateVar a`

A concrete implementation of a write-only state variable, carrying an IO action to write the new value.

`SettableStateVar :: (a -> IO ()) -> SettableStateVar a`

`makeSettableStateVar :: (a -> IO ()) -> SettableStateVar a`

Construct a SettableStateVar from an IO action for writing.

(a -> IO ()): setter

Updatable State Variables

`class HasSetter t b => HasUpdate t a b`

This is the class of all updatable state variables.

`($~) :: MonadIO m => t -> (a -> b) -> m ()`

Transform the contents of a state variable with a given funtion.

`($~!) :: MonadIO m => t -> (a -> b) -> m ()`

This is a variant of $~ which is strict in the transformed value.

`data StateVar a`

A concrete implementation of a readable and writable state variable, carrying one IO action to read the value and another IO action to write the new value. This data type represents a piece of mutable, imperative state with possible side-effects. These tend to encapsulate all sorts tricky behavior in external libraries, and may well throw exceptions. Inhabitants should satsify the following properties:

In the absence of concurrent mutation from other threads or a thrown exception:

do x <- 'get' v; v '$=' y; v '$=' x

should restore the previous state.

Ideally, in the absence of thrown exceptions:

v '$=' a >> 'get' v

should return a, regardless of a. In practice some StateVars only permit a very limited range of value assignments, and do not report failure.

`StateVar :: (IO a) -> (a -> IO ()) -> StateVar a`

`makeStateVar :: IO a -> (a -> IO ()) -> StateVar a`

Construct a StateVar from two IO actions, one for reading and one for writing.

getter

(a -> IO ()): setter

`mapStateVar :: (b -> a) -> (a -> b) -> StateVar a -> StateVar b`

Change the type of a StateVar

Instances

instance Typeable a => Typeable (StateVar a)
instance Contravariant SettableStateVar
instance Typeable a => Typeable (SettableStateVar a)
instance HasSetter (SettableStateVar a) a
instance HasSetter (StateVar a) a
instance Storable a => HasSetter (Ptr a) a
instance HasSetter (IORef a) a
instance HasSetter (TVar a) a
instance Storable a => HasSetter (ForeignPtr a) a
instance HasUpdate (StateVar a) a a
instance Storable a => HasUpdate (Ptr a) a a
instance HasUpdate (IORef a) a a
instance HasUpdate (TVar a) a a
instance Storable a => HasUpdate (ForeignPtr a) a a
instance HasGetter (StateVar a) a
instance HasGetter (TVar a) a
instance HasGetter (IO a) a
instance HasGetter (STM a) a
instance Storable a => HasGetter (Ptr a) a
instance HasGetter (IORef a) a
instance Storable a => HasGetter (ForeignPtr a) a

Maintainer: Sven Panne <svenpanne@gmail.com>
Portability: portable
License: BSD3

Build record and source files

Community contribution. The service has not verified this documentation. The generator reported 4 diagnostics.

Target: Linux on x86-64. Some inferred types and resolved links are not available.

Generator: aihc-haddock-aa6debbd-web-3

Metadata snapshot: a6a38a2e55e932fa2b5a7033238d9625595f9705090cad4ef67e443f4cb1abad

Open the dependency plan · Download the documentation model

StateVar-1.2.2 · Cabal revision 0 · Cabal file · Source archive
aihc-base-4.21.2.0 · Core library · Cabal file
aihc-prim-0.13.0 · Core library · Cabal file
aihc-rts-1.0.2 · Core library · Cabal file
array-0.5.8.0 · Cabal revision 2 · Cabal file · Source archive
stm-2.5.3.1 · Cabal revision 1 · Cabal file · Source archive
transformers-0.6.3.0 · Cabal revision 2 · Cabal file · Source archive