-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | State variables
--   
--   This package contains state variables, which are references in the IO
--   monad, like IORefs or parts of the OpenGL state.
@package StateVar
@version 1.2.1


-- | State variables are references in the IO monad, like <a>IORef</a>s 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 <a>StateVar</a>:
--   
--   <pre>
--   makeStateVarFromPtr :: Storable a =&gt; Ptr a -&gt; StateVar a
--   makeStateVarFromPtr p = makeStateVar (peek p) (poke p)
--   </pre>
--   
--   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:
--   
--   <pre>
--   do p &lt;- malloc :: IO (Ptr Int)
--      let v = makeStateVarFromPtr p
--      v $= 11
--      v $~ (+ 22)
--      x &lt;- get v
--      print x
--   </pre>
--   
--   However, <a>Ptr</a> can be used directly through the same API:
--   
--   <pre>
--   do p &lt;- malloc :: IO (Ptr Int)
--      p $= 11
--      p $~ (+ 22)
--      x &lt;- get p
--      print x
--   </pre>
--   
--   <a>IORef</a>s are state variables, too, so an example with them looks
--   extremely similiar:
--   
--   <pre>
--   do v &lt;- newIORef (0 :: Int)
--      v $= 11
--      v $~ (+ 22)
--      x &lt;- get v
--      print x
--   </pre>
module Data.StateVar

-- | This is the class of all readable state variables.
class HasGetter t a | t -> a
get :: (HasGetter t a, MonadIO m) => t -> m a

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

-- | Construct a <a>GettableStateVar</a> from an IO action.
makeGettableStateVar :: IO a -> GettableStateVar a

-- | This is the class of all writable state variables.
class HasSetter t a | t -> a

-- | Write a new value into a state variable.
($=) :: (HasSetter t a, MonadIO m) => t -> a -> m ()
infixr 2 $=

-- | This is a variant of <a>$=</a> which is strict in the value to be set.
($=!) :: (HasSetter t a, MonadIO m) => t -> a -> m ()
infixr 2 $=!

-- | A concrete implementation of a write-only state variable, carrying an
--   IO action to write the new value.
newtype SettableStateVar a
SettableStateVar :: (a -> IO ()) -> SettableStateVar a

-- | Construct a <a>SettableStateVar</a> from an IO action for writing.
makeSettableStateVar :: (a -> IO ()) -> SettableStateVar a

-- | This is the class of all updatable state variables.
class HasSetter t b => HasUpdate t a b | t -> a b

-- | Transform the contents of a state variable with a given funtion.
($~) :: (HasUpdate t a b, MonadIO m) => t -> (a -> b) -> m ()

-- | Transform the contents of a state variable with a given funtion.
($~) :: (HasUpdate t a b, MonadIO m, a ~ b, HasGetter t a) => t -> (a -> b) -> m ()

-- | This is a variant of <a>$~</a> which is strict in the transformed
--   value.
($~!) :: (HasUpdate t a b, MonadIO m) => t -> (a -> b) -> m ()

-- | This is a variant of <a>$~</a> which is strict in the transformed
--   value.
($~!) :: (HasUpdate t a b, MonadIO m, a ~ b, HasGetter t a) => t -> (a -> b) -> m ()
infixr 2 $~
infixr 2 $~!

-- | 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 <b>should</b> satsify the following
--   properties:
--   
--   <ul>
--   <li>In the absence of concurrent mutation from other threads or a
--   thrown exception:</li>
--   </ul>
--   
--   <pre>
--   do x &lt;- <a>get</a> v; v <a>$=</a> y; v <a>$=</a> x
--   </pre>
--   
--   should restore the previous state.
--   
--   <ul>
--   <li>Ideally, in the absence of thrown exceptions:</li>
--   </ul>
--   
--   <pre>
--   v <a>$=</a> a &gt;&gt; <a>get</a> v
--   </pre>
--   
--   should return <tt>a</tt>, regardless of <tt>a</tt>. In practice some
--   <a>StateVar</a>s only permit a very limited range of value
--   assignments, and do not report failure.
data StateVar a
StateVar :: IO a -> (a -> IO ()) -> StateVar a

-- | Construct a <a>StateVar</a> from two IO actions, one for reading and
--   one for
makeStateVar :: IO a -> (a -> IO ()) -> StateVar a

-- | Change the type of a <a>StateVar</a>
mapStateVar :: (b -> a) -> (a -> b) -> StateVar a -> StateVar b
instance Data.StateVar.HasUpdate (Data.StateVar.StateVar a) a a
instance Foreign.Storable.Storable a => Data.StateVar.HasUpdate (GHC.Ptr.Ptr a) a a
instance Data.StateVar.HasUpdate (GHC.IORef.IORef a) a a
instance Data.StateVar.HasUpdate (GHC.Conc.Sync.TVar a) a a
instance Foreign.Storable.Storable a => Data.StateVar.HasUpdate (GHC.ForeignPtr.ForeignPtr a) a a
instance Data.StateVar.HasGetter (Data.StateVar.StateVar a) a
instance Data.StateVar.HasGetter (GHC.Conc.Sync.TVar a) a
instance Data.StateVar.HasGetter (GHC.Types.IO a) a
instance Data.StateVar.HasGetter (GHC.Conc.Sync.STM a) a
instance Foreign.Storable.Storable a => Data.StateVar.HasGetter (GHC.Ptr.Ptr a) a
instance Data.StateVar.HasGetter (GHC.IORef.IORef a) a
instance Foreign.Storable.Storable a => Data.StateVar.HasGetter (GHC.ForeignPtr.ForeignPtr a) a
instance Data.StateVar.HasSetter (Data.StateVar.SettableStateVar a) a
instance Data.StateVar.HasSetter (Data.StateVar.StateVar a) a
instance Foreign.Storable.Storable a => Data.StateVar.HasSetter (GHC.Ptr.Ptr a) a
instance Data.StateVar.HasSetter (GHC.IORef.IORef a) a
instance Data.StateVar.HasSetter (GHC.Conc.Sync.TVar a) a
instance Foreign.Storable.Storable a => Data.StateVar.HasSetter (GHC.ForeignPtr.ForeignPtr a) a
instance Data.Functor.Contravariant.Contravariant Data.StateVar.SettableStateVar