-- 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,
--   &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 Ref 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 MVars. See the
--   documentation there for more info.
--   
--   This interface may be subject to future expansion. Presently, rather
--   than providing something like tryTakeMVar, instances for
--   "ReadRef sr m (Maybe a)" are provided, giving
--   readReference the same type tryTakeMRef would have if it
--   existed. There is currently nothing like tryPutMVar, though.
--   Perhaps there should be. Or, perhaps this is the sort of thing the
--   weird (to me) signature of atomicModifyIORef is for, and an
--   argument for a similar signature for modifyStateRef 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 :: Type -> Type) a
[MRef] :: forall sr (m :: Type -> Type) a. (TakeMRef sr m a, PutMRef sr m a) => !sr -> MRef m a
class HasMRef (m :: Type -> Type)
newMRef :: HasMRef m => a -> m (MRef m a)
newEmptyMRef :: HasMRef m => m (MRef m a)
class Monad m => NewMRef sr (m :: Type -> Type) a | sr -> a

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

-- | See newEmptyMVar
newEmptyMReference :: NewMRef sr m a => m sr
class Monad m => TakeMRef sr (m :: Type -> Type) a | sr -> a

-- | See takeMVar
takeMReference :: TakeMRef sr m a => sr -> m a
class Monad m => PutMRef sr (m :: Type -> Type) a | sr -> a

-- | See putMVar
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
--   Refs.
data Ref (m :: Type -> Type) a
[Ref] :: forall sr (m :: Type -> Type) a. ModifyRef sr m a => !sr -> Ref m a
class WriteRef sr (m :: Type -> Type) 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 :: Type -> Type) 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 :: Type -> Type) 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
--   atomicModifyReference 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 :: Type -> Type) a | sr -> a

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

-- | 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 IO monad.
--   
--   
--   >>> import GHC.Internal.Data.IORef
--   
--   >>> r <- newIORef 0
--   
--   >>> readIORef r
--   0
--   
--   >>> writeIORef r 1
--   
--   >>> readIORef r
--   1
--   
--   >>> atomicWriteIORef r 2
--   
--   >>> readIORef r
--   2
--   
--   >>> modifyIORef' r (+ 1)
--   
--   >>> readIORef r
--   3
--   
--   >>> atomicModifyIORef' r (\a -> (a + 1, ()))
--   
--   >>> readIORef r
--   4
--   
--   
--   See also STRef and MVar.
data IORef a

-- | An MVar (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 IO computations may be embedded. Any monad
--   built by applying a sequence of monad transformers to the IO
--   monad will be an instance of this class.
--   
--   Instances should satisfy the following laws, which state that
--   liftIO is a transformer of monads:
--   
--   
--   
- 
liftIO . return = return

--   
- 
liftIO (m >>= f) = liftIO m >>=
--   (liftIO . f)

--   
class Monad m => MonadIO (m :: Type -> Type)

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

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

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

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

-- | The type ForeignPtr 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 ForeignPtrs and vanilla memory
--   references of type Ptr a is that the former may be associated
--   with finalizers. 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
--   ForeignPtr. Typically, the finalizer will, then, invoke
--   routines in the foreign language that free the resources bound by the
--   foreign object.
--   
--   The ForeignPtr is parameterised in the same way as Ptr.
--   The type argument of ForeignPtr should normally be an instance
--   of class Storable.
data ForeignPtr a

-- | Shared memory locations that support atomic memory transactions.
data TVar a

-- | A monad supporting atomic memory transactions.
data STM a

-- | Perform a series of STM actions atomically.
--   
--   Using atomically inside an unsafePerformIO or
--   unsafeInterleaveIO 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 atomically inside unsafePerformIO
--   or unsafeInterleaveIO, 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 unsafePerformIO. See:
--   newTVarIO, newTChanIO, newBroadcastTChanIO,
--   newTQueueIO, newTBQueueIO, and newTMVarIO.
--   
--   Using unsafePerformIO inside of atomically is also
--   dangerous but for different reasons. See unsafeIOToSTM for more
--   on this.
atomically :: STM a -> IO a

-- | A TMVar 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

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

module Data.Accessor
newtype Getter (m :: Type -> Type) a
Getter :: m a -> Getter (m :: Type -> Type) a
newtype Setter (m :: Type -> Type) a
Setter :: (a -> m ()) -> Setter (m :: Type -> Type) a
newtype Accessor (m :: Type -> Type) a
Accessor :: (Getter m a, Setter m a) -> Accessor (m :: Type -> Type) a
instance GHC.Internal.Base.Monad m => Data.StateRef.Types.ReadRef (Data.Accessor.Accessor m a) m a
instance GHC.Internal.Base.Monad m => Data.StateRef.Types.ReadRef (Data.Accessor.Getter m a) m a
instance GHC.Internal.Base.Monad m => Data.StateRef.Types.WriteRef (Data.Accessor.Accessor m a) m a
instance GHC.Internal.Base.Monad m => Data.StateRef.Types.WriteRef (Data.Accessor.Setter 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 Ref. See readReference.
readRef :: Ref m a -> m a

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

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

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

-- | Essentially the same concept as gets, asks, 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 succ 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 TVar Double called
--   "clock", a useful value "dT" is yielded by the expression:
--   mkLapseReader 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 MVars, and
--   re-exports MVar.
module Data.MRef.Instances

-- | An MVar (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 IO computations may be embedded. Any monad
--   built by applying a sequence of monad transformers to the IO
--   monad will be an instance of this class.
--   
--   Instances should satisfy the following laws, which state that
--   liftIO is a transformer of monads:
--   
--   
--   
- 
liftIO . return = return

--   
- 
liftIO (m >>= f) = liftIO m >>=
--   (liftIO . f)

--   
class Monad m => MonadIO (m :: Type -> Type)

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

-- | Shared memory locations that support atomic memory transactions.
data TVar a

-- | A monad supporting atomic memory transactions.
data STM a

-- | Perform a series of STM actions atomically.
--   
--   Using atomically inside an unsafePerformIO or
--   unsafeInterleaveIO 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 atomically inside unsafePerformIO
--   or unsafeInterleaveIO, 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 unsafePerformIO. See:
--   newTVarIO, newTChanIO, newBroadcastTChanIO,
--   newTQueueIO, newTBQueueIO, and newTMVarIO.
--   
--   Using unsafePerformIO inside of atomically is also
--   dangerous but for different reasons. See unsafeIOToSTM for more
--   on this.
atomically :: STM a -> IO a

-- | A TMVar 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
instance Data.MRef.Types.HasMRef GHC.Types.IO
instance Control.Monad.IO.Class.MonadIO m => Data.MRef.Types.NewMRef (GHC.Internal.MVar.MVar a) m a
instance Control.Monad.IO.Class.MonadIO m => Data.MRef.Types.PutMRef (GHC.Internal.MVar.MVar a) m a
instance Control.Monad.IO.Class.MonadIO m => Data.MRef.Types.TakeMRef (GHC.Internal.MVar.MVar a) m a

module Data.MRef

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

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