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


-- | Abstraction for things that work like IORef.
--   
--   A collection of type-classes generalizing the read/write/modify
--   operations for stateful variables provided by things like IORef, TVar,
--   &amp;c. Note that The interface has changed a bit from the 0.2.*
--   version. "*Ref" functions are now called "*Reference" and new "*Ref"
--   function exist with simpler signatures. The new <a>Ref</a> existential
--   type provides a convenient monad-indexed reference type, and the
--   HasRef class indicates monads for which there is a default reference
--   type for every referent.
@package stateref
@version 0.3


-- | This module defines the "MRef" abstraction, which is a set of
--   type-classes for things that behave like <a>MVar</a>s. See the
--   documentation there for more info.
--   
--   This interface may be subject to future expansion. Presently, rather
--   than providing something like <a>tryTakeMVar</a>, instances for
--   "<a>ReadRef</a> sr m (<a>Maybe</a> a)" are provided, giving
--   <a>readReference</a> the same type tryTakeMRef would have if it
--   existed. There is currently nothing like <a>tryPutMVar</a>, though.
--   Perhaps there should be. Or, perhaps this is the sort of thing the
--   weird (to me) signature of <a>atomicModifyIORef</a> is for, and an
--   argument for a similar signature for <a>modifyStateRef</a> or the
--   addition of a new atomicModifyStateRef function.
--   
--   I would like to resolve these questions in version 0.3 of this
--   package.
module Data.MRef.Types
data MRef m a
[MRef] :: (TakeMRef sr m a, PutMRef sr m a) => !sr -> MRef m a
class HasMRef m
newMRef :: HasMRef m => a -> m (MRef m a)
newEmptyMRef :: HasMRef m => m (MRef m a)
class Monad m => NewMRef sr m a | sr -> a

-- | See <a>newMVar</a>
newMReference :: NewMRef sr m a => a -> m sr

-- | See <a>newEmptyMVar</a>
newEmptyMReference :: NewMRef sr m a => m sr
class Monad m => TakeMRef sr m a | sr -> a

-- | See <a>takeMVar</a>
takeMReference :: TakeMRef sr m a => sr -> m a
class Monad m => PutMRef sr m a | sr -> a

-- | See <a>putMVar</a>
putMReference :: PutMRef sr m a => sr -> a -> m ()

module Data.StateRef.Types

-- | A simple reference type, hiding the complexity of all these type
--   classes, since most of the time the only thing you care about is that
--   you want a reference. The full complexity is still there, though, so
--   FFI types or other reference-like things can still be made into
--   <a>Ref</a>s.
data Ref m a
[Ref] :: ModifyRef sr m a => !sr -> Ref m a
class WriteRef sr m a | sr -> a

-- | Replace the existing value of the given reference with the provided
--   value.
writeReference :: WriteRef sr m a => sr -> a -> m ()
class ReadRef sr m a | sr -> a

-- | Get the current value referenced by the given state reference.
readReference :: ReadRef sr m a => sr -> m a
class (ReadRef sr m a, WriteRef sr m a) => ModifyRef sr m a | sr -> a

-- | Atomically modify the contents of a reference. This is implemented in
--   a separate class (rather than a function with context (ReadRef sr m a,
--   WriteRef sr m a)) because in most cases the default implementation
--   cannot act atomically.
atomicModifyReference :: ModifyRef sr m a => sr -> (a -> (a, b)) -> m b

-- | Same thing, but don't thread out the extra return. Could perhaps be
--   implemented slightly more efficiently than
--   <a>atomicModifyReference</a> in many cases. Note that implementations
--   are expected to be atomic, if at all possible, but not strictly
--   required to be.
modifyReference :: ModifyRef sr m a => sr -> (a -> a) -> m ()

-- | Default implementation of atomicModifyReference in terms of
--   readReference and writeReference
defaultAtomicModifyReference :: (Monad m, ReadRef sr m t, WriteRef sr m a) => sr -> (t -> (a, b)) -> m b

-- | Default implementation of modifyReference in terms of readReference
--   and writeReference
defaultModifyReference :: (Monad m, ReadRef sr m t, WriteRef sr m a) => sr -> (t -> a) -> m ()
class NewRef sr m a | sr -> a

-- | Construct a new reference to the provided value.
newReference :: NewRef sr m a => a -> m sr
class HasRef m

-- | Construct a new mutable reference (of an unspecified implementation
--   type) containing the provided value.
newRef :: HasRef m => a -> m (Ref m a)


-- | This module exports no new symbols of its own. It defines several
--   basic class instances for creating, reading, and writing standard
--   reference types, and re-exports the types for which it defines
--   instances.
--   
--   TODO: add millions of SPECIALIZE INSTANCE pragmas, for IO monad at a
--   minimum.
module Data.StateRef.Instances

-- | A mutable variable in the <a>IO</a> monad.
--   
--   <pre>
--   &gt;&gt;&gt; import Data.IORef
--   
--   &gt;&gt;&gt; r &lt;- newIORef 0
--   
--   &gt;&gt;&gt; readIORef r
--   0
--   
--   &gt;&gt;&gt; writeIORef r 1
--   
--   &gt;&gt;&gt; readIORef r
--   1
--   
--   &gt;&gt;&gt; atomicWriteIORef r 2
--   
--   &gt;&gt;&gt; readIORef r
--   2
--   
--   &gt;&gt;&gt; modifyIORef' r (+ 1)
--   
--   &gt;&gt;&gt; readIORef r
--   3
--   
--   &gt;&gt;&gt; atomicModifyIORef' r (\a -&gt; (a + 1, ()))
--   
--   &gt;&gt;&gt; readIORef r
--   4
--   </pre>
--   
--   See also <a>STRef</a> and <a>MVar</a>.
data () => IORef a

-- | An <a>MVar</a> (pronounced "em-var") is a synchronising variable, used
--   for communication between concurrent threads. It can be thought of as
--   a box, which may be empty or full.
data () => MVar a

-- | Monads in which <a>IO</a> computations may be embedded. Any monad
--   built by applying a sequence of monad transformers to the <a>IO</a>
--   monad will be an instance of this class.
--   
--   Instances should satisfy the following laws, which state that
--   <a>liftIO</a> is a transformer of monads:
--   
--   <ul>
--   <li><pre><a>liftIO</a> . <a>return</a> = <a>return</a></pre></li>
--   <li><pre><a>liftIO</a> (m &gt;&gt;= f) = <a>liftIO</a> m &gt;&gt;=
--   (<a>liftIO</a> . f)</pre></li>
--   </ul>
class Monad m => MonadIO (m :: Type -> Type)

-- | Lift a computation from the <a>IO</a> monad. This allows us to run IO
--   computations in any monadic stack, so long as it supports these kinds
--   of operations (i.e. <a>IO</a> is the base monad for the stack).
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   import Control.Monad.Trans.State -- from the "transformers" library
--   
--   printState :: Show s =&gt; StateT s IO ()
--   printState = do
--     state &lt;- get
--     liftIO $ print state
--   </pre>
--   
--   Had we omitted <tt><a>liftIO</a></tt>, we would have ended up with
--   this error:
--   
--   <pre>
--   • Couldn't match type ‘IO’ with ‘StateT s IO’
--    Expected type: StateT s IO ()
--      Actual type: IO ()
--   </pre>
--   
--   The important part here is the mismatch between <tt>StateT s IO
--   ()</tt> and <tt><a>IO</a> ()</tt>.
--   
--   Luckily, we know of a function that takes an <tt><a>IO</a> a</tt> and
--   returns an <tt>(m a)</tt>: <tt><a>liftIO</a></tt>, enabling us to run
--   the program and see the expected results:
--   
--   <pre>
--   &gt; evalStateT printState "hello"
--   "hello"
--   
--   &gt; evalStateT printState 3
--   3
--   </pre>
liftIO :: MonadIO m => IO a -> m a

-- | a value of type <tt>STRef s a</tt> is a mutable variable in state
--   thread <tt>s</tt>, containing a value of type <tt>a</tt>
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   runST (do
--       ref &lt;- newSTRef "hello"
--       x &lt;- readSTRef ref
--       writeSTRef ref (x ++ "world")
--       readSTRef ref )
--   :}
--   "helloworld"
--   </pre>
data () => STRef s a

-- | The strict <a>ST</a> monad. The <a>ST</a> monad allows for destructive
--   updates, but is escapable (unlike IO). A computation of type
--   <tt><a>ST</a> s a</tt> returns a value of type <tt>a</tt>, and execute
--   in "thread" <tt>s</tt>. The <tt>s</tt> parameter is either
--   
--   <ul>
--   <li>an uninstantiated type variable (inside invocations of
--   <a>runST</a>), or</li>
--   <li><a>RealWorld</a> (inside invocations of <a>stToIO</a>).</li>
--   </ul>
--   
--   It serves to keep the internal states of different invocations of
--   <a>runST</a> separate from each other and from invocations of
--   <a>stToIO</a>.
--   
--   The <a>&gt;&gt;=</a> and <a>&gt;&gt;</a> operations are strict in the
--   state (though not in values stored in the state). For example,
--   
--   <pre>
--   <a>runST</a> (writeSTRef _|_ v &gt;&gt;= f) = _|_
--   </pre>
data () => ST s a

-- | <a>RealWorld</a> is deeply magical. It is <i>primitive</i>, but it is
--   not <i>unlifted</i> (hence <tt>ptrArg</tt>). We never manipulate
--   values of type <a>RealWorld</a>; it's only used in the type system, to
--   parameterise <a>State#</a>.
data RealWorld

-- | The type <a>ForeignPtr</a> represents references to objects that are
--   maintained in a foreign language, i.e., that are not part of the data
--   structures usually managed by the Haskell storage manager. The
--   essential difference between <a>ForeignPtr</a>s and vanilla memory
--   references of type <tt>Ptr a</tt> is that the former may be associated
--   with <i>finalizers</i>. A finalizer is a routine that is invoked when
--   the Haskell storage manager detects that - within the Haskell heap and
--   stack - there are no more references left that are pointing to the
--   <a>ForeignPtr</a>. Typically, the finalizer will, then, invoke
--   routines in the foreign language that free the resources bound by the
--   foreign object.
--   
--   The <a>ForeignPtr</a> is parameterised in the same way as <a>Ptr</a>.
--   The type argument of <a>ForeignPtr</a> should normally be an instance
--   of class <a>Storable</a>.
data () => ForeignPtr a

-- | A monad supporting atomic memory transactions.
data () => STM a

-- | Shared memory locations that support atomic memory transactions.
data () => TVar a

-- | A <a>TMVar</a> is a synchronising variable, used for communication
--   between concurrent threads. It can be thought of as a box, which may
--   be empty or full.
data () => TMVar a

-- | Perform a series of STM actions atomically.
--   
--   Using <a>atomically</a> inside an <a>unsafePerformIO</a> or
--   <a>unsafeInterleaveIO</a> subverts some of guarantees that STM
--   provides. It makes it possible to run a transaction inside of another
--   transaction, depending on when the thunk is evaluated. If a nested
--   transaction is attempted, an exception is thrown by the runtime. It is
--   possible to safely use <a>atomically</a> inside <a>unsafePerformIO</a>
--   or <a>unsafeInterleaveIO</a>, but the typechecker does not rule out
--   programs that may attempt nested transactions, meaning that the
--   programmer must take special care to prevent these.
--   
--   However, there are functions for creating transactional variables that
--   can always be safely called in <a>unsafePerformIO</a>. See:
--   <a>newTVarIO</a>, <a>newTChanIO</a>, <a>newBroadcastTChanIO</a>,
--   <a>newTQueueIO</a>, <a>newTBQueueIO</a>, and <a>newTMVarIO</a>.
--   
--   Using <a>unsafePerformIO</a> inside of <a>atomically</a> is also
--   dangerous but for different reasons. See <a>unsafeIOToSTM</a> for more
--   on this.
atomically :: STM a -> IO a

-- | Wrap a state reference that supports reading and writing, and add a
--   potentially thread-unsafe <a>ModifyRef</a> instance.
newtype UnsafeModifyRef sr
UnsafeModifyRef :: sr -> UnsafeModifyRef sr
instance Data.StateRef.Types.HasRef m => Data.StateRef.Types.NewRef (Data.StateRef.Types.Ref m a) m a
instance Data.StateRef.Types.ReadRef (Data.StateRef.Types.Ref m a) m a
instance Data.StateRef.Types.WriteRef (Data.StateRef.Types.Ref m a) m a
instance Data.StateRef.Types.ModifyRef (Data.StateRef.Types.Ref m a) m a
instance GHC.Base.Monad m => Data.StateRef.Types.NewRef (GHC.Types.IO a) m a
instance Control.Monad.IO.Class.MonadIO m => Data.StateRef.Types.ReadRef (GHC.Types.IO a) m a
instance GHC.Base.Monad m => Data.StateRef.Types.NewRef (GHC.ST.ST s a) m a
instance Data.StateRef.Types.ReadRef (GHC.ST.ST s a) (GHC.ST.ST s) a
instance Control.Monad.IO.Class.MonadIO m => Data.StateRef.Types.ReadRef (GHC.ST.ST GHC.Prim.RealWorld a) m a
instance Data.StateRef.Types.HasRef GHC.Types.IO
instance Control.Monad.IO.Class.MonadIO m => Data.StateRef.Types.NewRef (GHC.IORef.IORef a) m a
instance Control.Monad.IO.Class.MonadIO m => Data.StateRef.Types.ReadRef (GHC.IORef.IORef a) m a
instance Control.Monad.IO.Class.MonadIO m => Data.StateRef.Types.WriteRef (GHC.IORef.IORef a) m a
instance Control.Monad.IO.Class.MonadIO m => Data.StateRef.Types.ModifyRef (GHC.IORef.IORef a) m a
instance Data.StateRef.Types.HasRef (GHC.ST.ST s)
instance Data.StateRef.Types.NewRef (GHC.STRef.STRef s a) (GHC.ST.ST s) a
instance Data.StateRef.Types.ReadRef (GHC.STRef.STRef s a) (GHC.ST.ST s) a
instance Data.StateRef.Types.WriteRef (GHC.STRef.STRef s a) (GHC.ST.ST s) a
instance Data.StateRef.Types.ModifyRef (GHC.STRef.STRef s a) (GHC.ST.ST s) a
instance Data.StateRef.Types.NewRef (GHC.STRef.STRef GHC.Prim.RealWorld a) GHC.Types.IO a
instance Data.StateRef.Types.ReadRef (GHC.STRef.STRef GHC.Prim.RealWorld a) GHC.Types.IO a
instance Data.StateRef.Types.WriteRef (GHC.STRef.STRef GHC.Prim.RealWorld a) GHC.Types.IO a
instance Data.StateRef.Types.ModifyRef (GHC.STRef.STRef GHC.Prim.RealWorld a) GHC.Types.IO a
instance Data.StateRef.Types.HasRef (Control.Monad.ST.Lazy.Imp.ST s)
instance Data.StateRef.Types.NewRef (GHC.STRef.STRef s a) (Control.Monad.ST.Lazy.Imp.ST s) a
instance Data.StateRef.Types.ReadRef (GHC.STRef.STRef s a) (Control.Monad.ST.Lazy.Imp.ST s) a
instance Data.StateRef.Types.WriteRef (GHC.STRef.STRef s a) (Control.Monad.ST.Lazy.Imp.ST s) a
instance Data.StateRef.Types.ModifyRef (GHC.STRef.STRef s a) (Control.Monad.ST.Lazy.Imp.ST s) a
instance Control.Monad.IO.Class.MonadIO m => Data.StateRef.Types.NewRef (GHC.MVar.MVar a) m (GHC.Maybe.Maybe a)
instance (Foreign.Storable.Storable a, Control.Monad.IO.Class.MonadIO m) => Data.StateRef.Types.NewRef (GHC.ForeignPtr.ForeignPtr a) m a
instance (Foreign.Storable.Storable a, Control.Monad.IO.Class.MonadIO m) => Data.StateRef.Types.ReadRef (GHC.ForeignPtr.ForeignPtr a) m a
instance (Foreign.Storable.Storable a, Control.Monad.IO.Class.MonadIO m) => Data.StateRef.Types.WriteRef (GHC.ForeignPtr.ForeignPtr a) m a
instance (Foreign.Storable.Storable a, Control.Monad.IO.Class.MonadIO m) => Data.StateRef.Types.ModifyRef (GHC.ForeignPtr.ForeignPtr a) m a

module Data.Accessor
newtype Getter m a
Getter :: m a -> Getter m a
newtype Setter m a
Setter :: (a -> m ()) -> Setter m a
newtype Accessor m a
Accessor :: (Getter m a, Setter m a) -> Accessor m a
instance GHC.Base.Monad m => Data.StateRef.Types.ReadRef (Data.Accessor.Accessor m a) m a
instance GHC.Base.Monad m => Data.StateRef.Types.WriteRef (Data.Accessor.Accessor m a) m a
instance GHC.Base.Monad m => Data.StateRef.Types.WriteRef (Data.Accessor.Setter m a) m a
instance GHC.Base.Monad m => Data.StateRef.Types.ReadRef (Data.Accessor.Getter m a) m a


-- | This module provides classes and instances for mutable state
--   references. Various implementation exist in common usage, but no way
--   (until now ;-) to define functions using state references which don't
--   depend on the specific monad or reference type in use.
--   
--   These modules use several language extensions, including
--   multi-parameter type classes and functional dependencies.
module Data.StateRef

-- | Read a <a>Ref</a>. See <a>readReference</a>.
readRef :: Ref m a -> m a

-- | Write a <a>Ref</a>. See <a>writeReference</a>
writeRef :: Ref m a -> a -> m ()

-- | Modify a <a>Ref</a>. See <a>modifyReference</a>.
atomicModifyRef :: Ref m a -> (a -> (a, b)) -> m b

-- | Modify a <a>Ref</a>. See <a>modifyReference</a>.
modifyRef :: Ref m a -> (a -> a) -> m ()

-- | Essentially the same concept as <a>gets</a>, <a>asks</a>, et al.
--   Typically useful to read a field of a referenced ADT by passing a
--   record selector as the second argument.
readsRef :: (ReadRef sr m a, Monad m) => sr -> (a -> b) -> m b

-- | Construct a counter - a monadic value which, each time it is
--   evaluated, returns the <a>succ</a> of the previous value returned.
newCounter :: (HasRef m, Monad m, Enum a) => a -> m (m a)

-- | Create a "lapse reader" (suggestions for better terminology are more
--   than welcome), a sort of a time-lapse of the variable. The first
--   motivating instance for this operation was a clock in a simple
--   simulation application. Given a <a>TVar</a> <a>Double</a> called
--   "clock", a useful value "dT" is yielded by the expression:
--   <a>mkLapseReader</a> clock (-)
mkLapseReader :: (ReadRef sr m a, HasRef m, Monad m) => sr -> (a -> a -> b) -> m (m b)


-- | This module exports no new symbols of its own. It defines basic class
--   instances for creating, reading, and writing <a>MVar</a>s, and
--   re-exports <a>MVar</a>.
module Data.MRef.Instances

-- | An <a>MVar</a> (pronounced "em-var") is a synchronising variable, used
--   for communication between concurrent threads. It can be thought of as
--   a box, which may be empty or full.
data () => MVar a

-- | Monads in which <a>IO</a> computations may be embedded. Any monad
--   built by applying a sequence of monad transformers to the <a>IO</a>
--   monad will be an instance of this class.
--   
--   Instances should satisfy the following laws, which state that
--   <a>liftIO</a> is a transformer of monads:
--   
--   <ul>
--   <li><pre><a>liftIO</a> . <a>return</a> = <a>return</a></pre></li>
--   <li><pre><a>liftIO</a> (m &gt;&gt;= f) = <a>liftIO</a> m &gt;&gt;=
--   (<a>liftIO</a> . f)</pre></li>
--   </ul>
class Monad m => MonadIO (m :: Type -> Type)

-- | Lift a computation from the <a>IO</a> monad. This allows us to run IO
--   computations in any monadic stack, so long as it supports these kinds
--   of operations (i.e. <a>IO</a> is the base monad for the stack).
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   import Control.Monad.Trans.State -- from the "transformers" library
--   
--   printState :: Show s =&gt; StateT s IO ()
--   printState = do
--     state &lt;- get
--     liftIO $ print state
--   </pre>
--   
--   Had we omitted <tt><a>liftIO</a></tt>, we would have ended up with
--   this error:
--   
--   <pre>
--   • Couldn't match type ‘IO’ with ‘StateT s IO’
--    Expected type: StateT s IO ()
--      Actual type: IO ()
--   </pre>
--   
--   The important part here is the mismatch between <tt>StateT s IO
--   ()</tt> and <tt><a>IO</a> ()</tt>.
--   
--   Luckily, we know of a function that takes an <tt><a>IO</a> a</tt> and
--   returns an <tt>(m a)</tt>: <tt><a>liftIO</a></tt>, enabling us to run
--   the program and see the expected results:
--   
--   <pre>
--   &gt; evalStateT printState "hello"
--   "hello"
--   
--   &gt; evalStateT printState 3
--   3
--   </pre>
liftIO :: MonadIO m => IO a -> m a

-- | A monad supporting atomic memory transactions.
data () => STM a

-- | A <a>TMVar</a> is a synchronising variable, used for communication
--   between concurrent threads. It can be thought of as a box, which may
--   be empty or full.
data () => TMVar a

-- | Shared memory locations that support atomic memory transactions.
data () => TVar a

-- | Perform a series of STM actions atomically.
--   
--   Using <a>atomically</a> inside an <a>unsafePerformIO</a> or
--   <a>unsafeInterleaveIO</a> subverts some of guarantees that STM
--   provides. It makes it possible to run a transaction inside of another
--   transaction, depending on when the thunk is evaluated. If a nested
--   transaction is attempted, an exception is thrown by the runtime. It is
--   possible to safely use <a>atomically</a> inside <a>unsafePerformIO</a>
--   or <a>unsafeInterleaveIO</a>, but the typechecker does not rule out
--   programs that may attempt nested transactions, meaning that the
--   programmer must take special care to prevent these.
--   
--   However, there are functions for creating transactional variables that
--   can always be safely called in <a>unsafePerformIO</a>. See:
--   <a>newTVarIO</a>, <a>newTChanIO</a>, <a>newBroadcastTChanIO</a>,
--   <a>newTQueueIO</a>, <a>newTBQueueIO</a>, and <a>newTMVarIO</a>.
--   
--   Using <a>unsafePerformIO</a> inside of <a>atomically</a> is also
--   dangerous but for different reasons. See <a>unsafeIOToSTM</a> for more
--   on this.
atomically :: STM a -> IO a
instance Data.MRef.Types.HasMRef GHC.Types.IO
instance Control.Monad.IO.Class.MonadIO m => Data.MRef.Types.NewMRef (GHC.MVar.MVar a) m a
instance Control.Monad.IO.Class.MonadIO m => Data.MRef.Types.TakeMRef (GHC.MVar.MVar a) m a
instance Control.Monad.IO.Class.MonadIO m => Data.MRef.Types.PutMRef (GHC.MVar.MVar a) m a

module Data.MRef

-- | See <a>takeMRef</a>.
takeMRef :: MRef m a -> m a

-- | See <a>putMRef</a>.
putMRef :: MRef m a -> a -> m ()
