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


-- | State variables
--   
@package StateVar
@version 1.1.0.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
($=) :: (HasSetter t a, MonadIO m) => t -> a -> m ()

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

-- | 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 a => HasUpdate t a b | t -> a b where ($~) = defaultUpdate ($~!) = defaultUpdateStrict
($~) :: (HasUpdate t a b, MonadIO m) => t -> (a -> b) -> m ()
($~!) :: (HasUpdate t a b, MonadIO m) => t -> (a -> b) -> m ()

-- | 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 Typeable StateVar
instance Typeable SettableStateVar
instance HasGetter (IORef a) a
instance Storable a => HasGetter (Ptr a) a
instance HasGetter (STM a) a
instance HasGetter (IO a) a
instance HasGetter (TVar a) a
instance HasGetter (StateVar a) a
instance HasUpdate (TVar a) a a
instance HasUpdate (IORef a) a a
instance Storable a => HasUpdate (Ptr a) a a
instance HasUpdate (StateVar a) a a
instance HasSetter (TVar a) a
instance HasSetter (IORef a) a
instance Storable a => HasSetter (Ptr a) a
instance HasSetter (StateVar a) a
instance HasSetter (SettableStateVar a) a