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


-- | lifted IO operations from the base library
--   
--   <tt>lifted-base</tt> exports IO operations from the base library
--   lifted to any instance of <a>MonadBase</a> or <a>MonadBaseControl</a>.
--   
--   Note that not all modules from <tt>base</tt> are converted yet. If you
--   need a lifted version of a function from <tt>base</tt>, just ask me to
--   add it or send me a patch.
--   
--   The package includes a copy of the <tt>monad-peel</tt> testsuite
--   written by Anders Kaseorg The tests can be performed using <tt>cabal
--   test</tt>.
@package lifted-base
@version 0.2.3.12


-- | This is a wrapped version of <a>Control.Concurrent.Chan</a> with types
--   generalised from <a>IO</a> to all monads in <a>MonadBase</a>.
--   
--   <a>unGetChan</a> and <a>isEmptyChan</a> are deprecated in
--   <tt>base</tt>, therefore they are not included here. Use <a>TVar</a>
--   instead.
module Control.Concurrent.Chan.Lifted

-- | <a>Chan</a> is an abstract type representing an unbounded FIFO
--   channel.
data Chan a

-- | Generalized version of <a>newChan</a>.
newChan :: MonadBase IO m => m (Chan a)

-- | Generalized version of <a>writeChan</a>.
writeChan :: MonadBase IO m => Chan a -> a -> m ()

-- | Generalized version of <a>readChan</a>.
readChan :: MonadBase IO m => Chan a -> m a

-- | Generalized version of <a>dupChan</a>.
dupChan :: MonadBase IO m => Chan a -> m (Chan a)

-- | Generalized version of <a>getChanContents</a>.
getChanContents :: MonadBase IO m => Chan a -> m [a]

-- | Generalized version of <a>writeList2Chan</a>.
writeList2Chan :: MonadBase IO m => Chan a -> [a] -> m ()


-- | This is a wrapped version of <a>Control.Concurrent.MVar</a> with types
--   generalized from <a>IO</a> to all monads in either <a>MonadBase</a> or
--   <a>MonadBaseControl</a>.
module Control.Concurrent.MVar.Lifted

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

-- | Generalized version of <a>newEmptyMVar</a>.
newEmptyMVar :: MonadBase IO m => m (MVar a)

-- | Generalized version of <a>newMVar</a>.
newMVar :: MonadBase IO m => a -> m (MVar a)

-- | Generalized version of <a>takeMVar</a>.
takeMVar :: MonadBase IO m => MVar a -> m a

-- | Generalized version of <a>putMVar</a>.
putMVar :: MonadBase IO m => MVar a -> a -> m ()

-- | Generalized version of <a>readMVar</a>.
readMVar :: MonadBase IO m => MVar a -> m a

-- | Generalized version of <a>swapMVar</a>.
swapMVar :: MonadBase IO m => MVar a -> a -> m a

-- | Generalized version of <a>tryTakeMVar</a>.
tryTakeMVar :: MonadBase IO m => MVar a -> m (Maybe a)

-- | Generalized version of <a>tryPutMVar</a>.
tryPutMVar :: MonadBase IO m => MVar a -> a -> m Bool

-- | Generalized version of <a>isEmptyMVar</a>.
isEmptyMVar :: MonadBase IO m => MVar a -> m Bool

-- | Generalized version of <a>withMVar</a>.
withMVar :: MonadBaseControl IO m => MVar a -> (a -> m b) -> m b

-- | Generalized version of <a>modifyMVar_</a>.
modifyMVar_ :: MonadBaseControl IO m => MVar a -> (a -> m a) -> m ()

-- | Generalized version of <a>modifyMVar</a>.
modifyMVar :: MonadBaseControl IO m => MVar a -> (a -> m (a, b)) -> m b

-- | Generalized version of <a>modifyMVarMasked_</a>.
modifyMVarMasked_ :: MonadBaseControl IO m => MVar a -> (a -> m a) -> m ()

-- | Generalized version of <a>modifyMVarMasked</a>.
modifyMVarMasked :: MonadBaseControl IO m => MVar a -> (a -> m (a, b)) -> m b

-- | Generalized version of <a>mkWeakMVar</a>.
--   
--   Note any monadic side effects in <tt>m</tt> of the "finalizer"
--   computation are discarded.
mkWeakMVar :: MonadBaseControl IO m => MVar a -> m () -> m (Weak (MVar a))

-- | Generalized version of <a>withMVarMasked</a>.
withMVarMasked :: MonadBaseControl IO m => MVar a -> (a -> m b) -> m b

-- | Generalized version of <a>tryReadMVar</a>.
tryReadMVar :: MonadBase IO m => MVar a -> m (Maybe a)


-- | This is a wrapped version of <a>Control.Concurrent.QSem</a> with types
--   generalised from <a>IO</a> to all monads in <a>MonadBase</a>.
module Control.Concurrent.QSem.Lifted

-- | <a>QSem</a> is a quantity semaphore in which the resource is acquired
--   and released in units of one. It provides guaranteed FIFO ordering for
--   satisfying blocked <a>waitQSem</a> calls.
--   
--   The pattern
--   
--   <pre>
--   bracket_ waitQSem signalQSem (...)
--   </pre>
--   
--   is safe; it never loses a unit of the resource.
data QSem

-- | Generalized version of <a>newQSem</a>.
newQSem :: MonadBase IO m => Int -> m QSem

-- | Generalized version of <a>waitQSem</a>.
waitQSem :: MonadBase IO m => QSem -> m ()

-- | Generalized version of <a>signalQSem</a>.
signalQSem :: MonadBase IO m => QSem -> m ()


-- | This is a wrapped version of <a>Control.Concurrent.QSemN</a> with
--   types generalised from <a>IO</a> to all monads in <a>MonadBase</a>.
module Control.Concurrent.QSemN.Lifted

-- | <a>QSemN</a> is a quantity semaphore in which the resource is acquired
--   and released in units of one. It provides guaranteed FIFO ordering for
--   satisfying blocked <a>waitQSemN</a> calls.
--   
--   The pattern
--   
--   <pre>
--   bracket_ (waitQSemN n) (signalQSemN n) (...)
--   </pre>
--   
--   is safe; it never loses any of the resource.
data QSemN

-- | Generalized version of <a>newQSemN</a>.
newQSemN :: MonadBase IO m => Int -> m QSemN

-- | Generalized version of <a>waitQSemN</a>.
waitQSemN :: MonadBase IO m => QSemN -> Int -> m ()

-- | Generalized version of <a>signalQSemN</a>.
signalQSemN :: MonadBase IO m => QSemN -> Int -> m ()


-- | This is a wrapped version of <a>Control.Exception</a> with types
--   generalized from <a>IO</a> to all monads in either <a>MonadBase</a> or
--   <a>MonadBaseControl</a>.
module Control.Exception.Lifted

-- | If the first argument evaluates to <a>True</a>, then the result is the
--   second argument. Otherwise an <a>AssertionFailed</a> exception is
--   raised, containing a <a>String</a> with the source file and line
--   number of the call to <a>assert</a>.
--   
--   Assertions can normally be turned on or off with a compiler flag (for
--   GHC, assertions are normally on unless optimisation is turned on with
--   <tt>-O</tt> or the <tt>-fignore-asserts</tt> option is given). When
--   assertions are turned off, the first argument to <a>assert</a> is
--   ignored, and the second argument is returned as the result.
assert :: Bool -> a -> a

-- | An expression that didn't typecheck during compile time was called.
--   This is only possible with -fdefer-type-errors. The <tt>String</tt>
--   gives details about the failed type check.
newtype TypeError
TypeError :: String -> TypeError

-- | A record update was performed on a constructor without the appropriate
--   field. This can only happen with a datatype with multiple
--   constructors, where some fields are in one constructor but not
--   another. The <tt>String</tt> gives information about the source
--   location of the record update.
newtype RecUpdError
RecUpdError :: String -> RecUpdError

-- | A record selector was applied to a constructor without the appropriate
--   field. This can only happen with a datatype with multiple
--   constructors, where some fields are in one constructor but not
--   another. The <tt>String</tt> gives information about the source
--   location of the record selector.
newtype RecSelError
RecSelError :: String -> RecSelError

-- | An uninitialised record field was used. The <tt>String</tt> gives
--   information about the source location where the record was
--   constructed.
newtype RecConError
RecConError :: String -> RecConError

-- | A pattern match failed. The <tt>String</tt> gives information about
--   the source location of the pattern.
newtype PatternMatchFail
PatternMatchFail :: String -> PatternMatchFail

-- | Thrown when the runtime system detects that the computation is
--   guaranteed not to terminate. Note that there is no guarantee that the
--   runtime system will notice whether any given computation is guaranteed
--   to terminate or not.
data NonTermination
NonTermination :: NonTermination

-- | A class method without a definition (neither a default definition, nor
--   a definition in the appropriate instance) was called. The
--   <tt>String</tt> gives information about which method it was.
newtype NoMethodError
NoMethodError :: String -> NoMethodError

-- | Thrown when the program attempts to call <tt>atomically</tt>, from the
--   <tt>stm</tt> package, inside another call to <tt>atomically</tt>.
data NestedAtomically
NestedAtomically :: NestedAtomically

-- | This function maps one exception into another as proposed in the paper
--   "A semantics for imprecise exceptions".
mapException :: (Exception e1, Exception e2) => (e1 -> e2) -> a -> a

-- | Superclass for asynchronous exceptions.
data SomeAsyncException
SomeAsyncException :: e -> SomeAsyncException

-- | There are no runnable threads, so the program is deadlocked. The
--   <tt>Deadlock</tt> exception is raised in the main thread only.
data Deadlock
Deadlock :: Deadlock

-- | Compaction found an object that cannot be compacted. Functions cannot
--   be compacted, nor can mutable objects or pinned objects. See
--   <a>compact</a>.
newtype CompactionFailed
CompactionFailed :: String -> CompactionFailed

-- | The thread is waiting to retry an STM transaction, but there are no
--   other references to any <tt>TVar</tt>s involved, so it can't ever
--   continue.
data BlockedIndefinitelyOnSTM
BlockedIndefinitelyOnSTM :: BlockedIndefinitelyOnSTM

-- | The thread is blocked on an <tt>MVar</tt>, but there are no other
--   references to the <tt>MVar</tt> so it can't ever continue.
data BlockedIndefinitelyOnMVar
BlockedIndefinitelyOnMVar :: BlockedIndefinitelyOnMVar

-- | Asynchronous exceptions.
data AsyncException

-- | The current thread's stack exceeded its limit. Since an exception has
--   been raised, the thread's stack will certainly be below its limit
--   again, but the programmer should take remedial action immediately.
StackOverflow :: AsyncException

-- | The program's heap is reaching its limit, and the program should take
--   action to reduce the amount of live data it has. Notes:
--   
--   <ul>
--   <li>It is undefined which thread receives this exception. GHC
--   currently throws this to the same thread that receives
--   <a>UserInterrupt</a>, but this may change in the future.</li>
--   <li>The GHC RTS currently can only recover from heap overflow if it
--   detects that an explicit memory limit (set via RTS flags). has been
--   exceeded. Currently, failure to allocate memory from the operating
--   system results in immediate termination of the program.</li>
--   </ul>
HeapOverflow :: AsyncException

-- | This exception is raised by another thread calling <a>killThread</a>,
--   or by the system if it needs to terminate the thread for some reason.
ThreadKilled :: AsyncException

-- | This exception is raised by default in the main thread of the program
--   when the user requests to terminate the program via the usual
--   mechanism(s) (e.g. Control-C in the console).
UserInterrupt :: AsyncException

-- | <a>assert</a> was applied to <a>False</a>.
newtype AssertionFailed
AssertionFailed :: String -> AssertionFailed

-- | Exceptions generated by array operations
data ArrayException

-- | An attempt was made to index an array outside its declared bounds.
IndexOutOfBounds :: String -> ArrayException

-- | An attempt was made to evaluate an element of an array that had not
--   been initialized.
UndefinedElement :: String -> ArrayException

-- | This thread has exceeded its allocation limit. See
--   <a>setAllocationCounter</a> and <a>enableAllocationLimit</a>.
data AllocationLimitExceeded
AllocationLimitExceeded :: AllocationLimitExceeded

asyncExceptionToException :: Exception e => e -> SomeException

asyncExceptionFromException :: Exception e => SomeException -> Maybe e

-- | Describes the behaviour of a thread when an asynchronous exception is
--   received.
data MaskingState

-- | asynchronous exceptions are unmasked (the normal state)
Unmasked :: MaskingState

-- | the state during <a>mask</a>: asynchronous exceptions are masked, but
--   blocking operations may still be interrupted
MaskedInterruptible :: MaskingState

-- | the state during <a>uninterruptibleMask</a>: asynchronous exceptions
--   are masked, and blocking operations may not be interrupted
MaskedUninterruptible :: MaskingState

-- | Allow asynchronous exceptions to be raised even inside <a>mask</a>,
--   making the operation interruptible (see the discussion of
--   "Interruptible operations" in <a>Exception</a>).
--   
--   When called outside <a>mask</a>, or inside <a>uninterruptibleMask</a>,
--   this function has no effect.
interruptible :: IO a -> IO a

-- | Exceptions that occur in the <tt>IO</tt> monad. An
--   <tt>IOException</tt> records a more specific error type, a descriptive
--   string and maybe the handle that was used when the error was flagged.
data IOException

-- | This is thrown when the user calls <a>error</a>. The first
--   <tt>String</tt> is the argument given to <a>error</a>, second
--   <tt>String</tt> is the location.
data ErrorCall
ErrorCallWithLocation :: String -> String -> ErrorCall
pattern ErrorCall :: String -> ErrorCall

-- | Throw an exception. Exceptions may be thrown from purely functional
--   code, but may only be caught within the <a>IO</a> monad.
throw :: forall (r :: RuntimeRep) (a :: TYPE r) e. Exception e => e -> a

-- | Any type that you wish to throw or catch as an exception must be an
--   instance of the <tt>Exception</tt> class. The simplest case is a new
--   exception type directly below the root:
--   
--   <pre>
--   data MyException = ThisException | ThatException
--       deriving Show
--   
--   instance Exception MyException
--   </pre>
--   
--   The default method definitions in the <tt>Exception</tt> class do what
--   we need in this case. You can now throw and catch
--   <tt>ThisException</tt> and <tt>ThatException</tt> as exceptions:
--   
--   <pre>
--   *Main&gt; throw ThisException `catch` \e -&gt; putStrLn ("Caught " ++ show (e :: MyException))
--   Caught ThisException
--   </pre>
--   
--   In more complicated examples, you may wish to define a whole hierarchy
--   of exceptions:
--   
--   <pre>
--   ---------------------------------------------------------------------
--   -- Make the root exception type for all the exceptions in a compiler
--   
--   data SomeCompilerException = forall e . Exception e =&gt; SomeCompilerException e
--   
--   instance Show SomeCompilerException where
--       show (SomeCompilerException e) = show e
--   
--   instance Exception SomeCompilerException
--   
--   compilerExceptionToException :: Exception e =&gt; e -&gt; SomeException
--   compilerExceptionToException = toException . SomeCompilerException
--   
--   compilerExceptionFromException :: Exception e =&gt; SomeException -&gt; Maybe e
--   compilerExceptionFromException x = do
--       SomeCompilerException a &lt;- fromException x
--       cast a
--   
--   ---------------------------------------------------------------------
--   -- Make a subhierarchy for exceptions in the frontend of the compiler
--   
--   data SomeFrontendException = forall e . Exception e =&gt; SomeFrontendException e
--   
--   instance Show SomeFrontendException where
--       show (SomeFrontendException e) = show e
--   
--   instance Exception SomeFrontendException where
--       toException = compilerExceptionToException
--       fromException = compilerExceptionFromException
--   
--   frontendExceptionToException :: Exception e =&gt; e -&gt; SomeException
--   frontendExceptionToException = toException . SomeFrontendException
--   
--   frontendExceptionFromException :: Exception e =&gt; SomeException -&gt; Maybe e
--   frontendExceptionFromException x = do
--       SomeFrontendException a &lt;- fromException x
--       cast a
--   
--   ---------------------------------------------------------------------
--   -- Make an exception type for a particular frontend compiler exception
--   
--   data MismatchedParentheses = MismatchedParentheses
--       deriving Show
--   
--   instance Exception MismatchedParentheses where
--       toException   = frontendExceptionToException
--       fromException = frontendExceptionFromException
--   </pre>
--   
--   We can now catch a <tt>MismatchedParentheses</tt> exception as
--   <tt>MismatchedParentheses</tt>, <tt>SomeFrontendException</tt> or
--   <tt>SomeCompilerException</tt>, but not other types, e.g.
--   <tt>IOException</tt>:
--   
--   <pre>
--   *Main&gt; throw MismatchedParentheses `catch` \e -&gt; putStrLn ("Caught " ++ show (e :: MismatchedParentheses))
--   Caught MismatchedParentheses
--   *Main&gt; throw MismatchedParentheses `catch` \e -&gt; putStrLn ("Caught " ++ show (e :: SomeFrontendException))
--   Caught MismatchedParentheses
--   *Main&gt; throw MismatchedParentheses `catch` \e -&gt; putStrLn ("Caught " ++ show (e :: SomeCompilerException))
--   Caught MismatchedParentheses
--   *Main&gt; throw MismatchedParentheses `catch` \e -&gt; putStrLn ("Caught " ++ show (e :: IOException))
--   *** Exception: MismatchedParentheses
--   </pre>
class (Typeable e, Show e) => Exception e
toException :: Exception e => e -> SomeException
fromException :: Exception e => SomeException -> Maybe e

-- | Render this exception value in a human-friendly manner.
--   
--   Default implementation: <tt><a>show</a></tt>.
displayException :: Exception e => e -> String

-- | Arithmetic exceptions.
data ArithException
Overflow :: ArithException
Underflow :: ArithException
LossOfPrecision :: ArithException
DivideByZero :: ArithException
Denormal :: ArithException

RatioZeroDenominator :: ArithException

-- | The <tt>SomeException</tt> type is the root of the exception type
--   hierarchy. When an exception of type <tt>e</tt> is thrown, behind the
--   scenes it is encapsulated in a <tt>SomeException</tt>.
data SomeException
SomeException :: e -> SomeException

-- | Generalized version of <a>throwIO</a>.
throwIO :: (MonadBase IO m, Exception e) => e -> m a

-- | Generalized version of <a>ioError</a>.
ioError :: MonadBase IO m => IOError -> m a

-- | Generalized version of <a>throwTo</a>.
throwTo :: (MonadBase IO m, Exception e) => ThreadId -> e -> m ()

-- | Generalized version of <a>catch</a>.
--   
--   Note, when the given computation throws an exception any monadic side
--   effects in <tt>m</tt> will be discarded.
catch :: (MonadBaseControl IO m, Exception e) => m a -> (e -> m a) -> m a

-- | Generalized version of <a>catches</a>.
--   
--   Note, when the given computation throws an exception any monadic side
--   effects in <tt>m</tt> will be discarded.
catches :: MonadBaseControl IO m => m a -> [Handler m a] -> m a

-- | Generalized version of <a>Handler</a>.
data Handler m a
Handler :: (e -> m a) -> Handler m a

-- | Generalized version of <a>catchJust</a>.
--   
--   Note, when the given computation throws an exception any monadic side
--   effects in <tt>m</tt> will be discarded.
catchJust :: (MonadBaseControl IO m, Exception e) => (e -> Maybe b) -> m a -> (b -> m a) -> m a

-- | Generalized version of <a>handle</a>.
--   
--   Note, when the given computation throws an exception any monadic side
--   effects in <tt>m</tt> will be discarded.
handle :: (MonadBaseControl IO m, Exception e) => (e -> m a) -> m a -> m a

-- | Generalized version of <a>handleJust</a>.
--   
--   Note, when the given computation throws an exception any monadic side
--   effects in <tt>m</tt> will be discarded.
handleJust :: (MonadBaseControl IO m, Exception e) => (e -> Maybe b) -> (b -> m a) -> m a -> m a

-- | Generalized version of <a>try</a>.
--   
--   Note, when the given computation throws an exception any monadic side
--   effects in <tt>m</tt> will be discarded.
try :: (MonadBaseControl IO m, Exception e) => m a -> m (Either e a)

-- | Generalized version of <a>tryJust</a>.
--   
--   Note, when the given computation throws an exception any monadic side
--   effects in <tt>m</tt> will be discarded.
tryJust :: (MonadBaseControl IO m, Exception e) => (e -> Maybe b) -> m a -> m (Either b a)

-- | Generalized version of <a>evaluate</a>.
evaluate :: MonadBase IO m => a -> m a

-- | Generalized version of <a>mask</a>.
mask :: MonadBaseControl IO m => ((forall a. m a -> m a) -> m b) -> m b

-- | Generalized version of <a>mask_</a>.
mask_ :: MonadBaseControl IO m => m a -> m a

-- | Generalized version of <a>uninterruptibleMask</a>.
uninterruptibleMask :: MonadBaseControl IO m => ((forall a. m a -> m a) -> m b) -> m b

-- | Generalized version of <a>uninterruptibleMask_</a>.
uninterruptibleMask_ :: MonadBaseControl IO m => m a -> m a

-- | Generalized version of <a>getMaskingState</a>.
getMaskingState :: MonadBase IO m => m MaskingState

-- | Generalized version of <a>allowInterrupt</a>.
allowInterrupt :: MonadBase IO m => m ()

-- | Generalized version of <a>bracket</a>.
--   
--   Note:
--   
--   <ul>
--   <li>When the "acquire" or "release" computations throw exceptions any
--   monadic side effects in <tt>m</tt> will be discarded.</li>
--   <li>When the "in-between" computation throws an exception any monadic
--   side effects in <tt>m</tt> produced by that computation will be
--   discarded but the side effects of the "acquire" or "release"
--   computations will be retained.</li>
--   <li>Also, any monadic side effects in <tt>m</tt> of the "release"
--   computation will be discarded; it is run only for its side effects in
--   <tt>IO</tt>.</li>
--   </ul>
--   
--   Note that when your <tt>acquire</tt> and <tt>release</tt> computations
--   are of type <a>IO</a> it will be more efficient to write:
--   
--   <pre>
--   <tt>liftBaseOp</tt> (<a>bracket</a> acquire release)
--   </pre>
bracket :: MonadBaseControl IO m => m a -> (a -> m b) -> (a -> m c) -> m c

-- | Generalized version of <a>bracket_</a>.
--   
--   Note any monadic side effects in <tt>m</tt> of <i>both</i> the
--   "acquire" and "release" computations will be discarded. To keep the
--   monadic side effects of the "acquire" computation, use <a>bracket</a>
--   with constant functions instead.
--   
--   Note that when your <tt>acquire</tt> and <tt>release</tt> computations
--   are of type <a>IO</a> it will be more efficient to write:
--   
--   <pre>
--   <a>liftBaseOp_</a> (<a>bracket_</a> acquire release)
--   </pre>
bracket_ :: MonadBaseControl IO m => m a -> m b -> m c -> m c

-- | Generalized version of <a>bracketOnError</a>.
--   
--   Note:
--   
--   <ul>
--   <li>When the "acquire" or "release" computations throw exceptions any
--   monadic side effects in <tt>m</tt> will be discarded.</li>
--   <li>When the "in-between" computation throws an exception any monadic
--   side effects in <tt>m</tt> produced by that computation will be
--   discarded but the side effects of the "acquire" computation will be
--   retained.</li>
--   <li>Also, any monadic side effects in <tt>m</tt> of the "release"
--   computation will be discarded; it is run only for its side effects in
--   <tt>IO</tt>.</li>
--   </ul>
--   
--   Note that when your <tt>acquire</tt> and <tt>release</tt> computations
--   are of type <a>IO</a> it will be more efficient to write:
--   
--   <pre>
--   <tt>liftBaseOp</tt> (<a>bracketOnError</a> acquire release)
--   </pre>
bracketOnError :: MonadBaseControl IO m => m a -> (a -> m b) -> (a -> m c) -> m c

-- | Generalized version of <a>finally</a>.
--   
--   Note, any monadic side effects in <tt>m</tt> of the "afterward"
--   computation will be discarded.
finally :: MonadBaseControl IO m => m a -> m b -> m a

-- | Generalized version of <a>onException</a>.
--   
--   Note, any monadic side effects in <tt>m</tt> of the "afterward"
--   computation will be discarded.
onException :: MonadBaseControl IO m => m a -> m b -> m a


-- | This is a wrapped version of <a>Control.Concurrent</a> with types
--   generalized from <a>IO</a> to all monads in either <a>MonadBase</a> or
--   <a>MonadBaseControl</a>.
module Control.Concurrent.Lifted

-- | A <a>ThreadId</a> is an abstract type representing a handle to a
--   thread. <a>ThreadId</a> is an instance of <a>Eq</a>, <a>Ord</a> and
--   <a>Show</a>, where the <a>Ord</a> instance implements an arbitrary
--   total ordering over <a>ThreadId</a>s. The <a>Show</a> instance lets
--   you convert an arbitrary-valued <a>ThreadId</a> to string form;
--   showing a <a>ThreadId</a> value is occasionally useful when debugging
--   or diagnosing the behaviour of a concurrent program.
--   
--   <i>Note</i>: in GHC, if you have a <a>ThreadId</a>, you essentially
--   have a pointer to the thread itself. This means the thread itself
--   can't be garbage collected until you drop the <a>ThreadId</a>. This
--   misfeature will hopefully be corrected at a later date.
data ThreadId

-- | Generalized version of <a>myThreadId</a>.
myThreadId :: MonadBase IO m => m ThreadId

-- | Generalized version of <a>forkIO</a>.
--   
--   Note that, while the forked computation <tt>m ()</tt> has access to
--   the captured state, all its side-effects in <tt>m</tt> are discarded.
--   It is run only for its side-effects in <a>IO</a>.
fork :: MonadBaseControl IO m => m () -> m ThreadId

-- | Generalized version of <a>forkIOWithUnmask</a>.
--   
--   Note that, while the forked computation <tt>m ()</tt> has access to
--   the captured state, all its side-effects in <tt>m</tt> are discarded.
--   It is run only for its side-effects in <a>IO</a>.
forkWithUnmask :: MonadBaseControl IO m => ((forall a. m a -> m a) -> m ()) -> m ThreadId

-- | Generalized version of <a>forkFinally</a>.
--   
--   Note that in <tt>forkFinally action and_then</tt>, while the forked
--   <tt>action</tt> and the <tt>and_then</tt> function have access to the
--   captured state, all their side-effects in <tt>m</tt> are discarded.
--   They're run only for their side-effects in <a>IO</a>.
forkFinally :: MonadBaseControl IO m => m a -> (Either SomeException a -> m ()) -> m ThreadId

-- | Generalized version of <a>killThread</a>.
killThread :: MonadBase IO m => ThreadId -> m ()

-- | Generalized version of <a>throwTo</a>.
throwTo :: (MonadBase IO m, Exception e) => ThreadId -> e -> m ()

-- | Generalized version of <a>forkOn</a>.
--   
--   Note that, while the forked computation <tt>m ()</tt> has access to
--   the captured state, all its side-effects in <tt>m</tt> are discarded.
--   It is run only for its side-effects in <a>IO</a>.
forkOn :: MonadBaseControl IO m => Int -> m () -> m ThreadId

-- | Generalized version of <a>forkOnWithUnmask</a>.
--   
--   Note that, while the forked computation <tt>m ()</tt> has access to
--   the captured state, all its side-effects in <tt>m</tt> are discarded.
--   It is run only for its side-effects in <a>IO</a>.
forkOnWithUnmask :: MonadBaseControl IO m => Int -> ((forall a. m a -> m a) -> m ()) -> m ThreadId

-- | Generalized version of <a>getNumCapabilities</a>.
getNumCapabilities :: MonadBase IO m => m Int

-- | Generalized version of <a>setNumCapabilities</a>.
setNumCapabilities :: MonadBase IO m => Int -> m ()

-- | Generalized version of <a>threadCapability</a>.
threadCapability :: MonadBase IO m => ThreadId -> m (Int, Bool)

-- | Generalized version of <a>yield</a>.
yield :: MonadBase IO m => m ()

-- | Generalized version of <a>threadDelay</a>.
threadDelay :: MonadBase IO m => Int -> m ()

-- | Generalized version of <a>threadWaitRead</a>.
threadWaitRead :: MonadBase IO m => Fd -> m ()

-- | Generalized version of <a>threadWaitWrite</a>.
threadWaitWrite :: MonadBase IO m => Fd -> m ()

-- | <a>True</a> if bound threads are supported. If
--   <tt>rtsSupportsBoundThreads</tt> is <a>False</a>,
--   <a>isCurrentThreadBound</a> will always return <a>False</a> and both
--   <a>forkOS</a> and <a>runInBoundThread</a> will fail.
rtsSupportsBoundThreads :: Bool

-- | Generalized version of <a>forkOS</a>.
--   
--   Note that, while the forked computation <tt>m ()</tt> has access to
--   the captured state, all its side-effects in <tt>m</tt> are discarded.
--   It is run only for its side-effects in <a>IO</a>.
forkOS :: MonadBaseControl IO m => m () -> m ThreadId

-- | Generalized version of <a>isCurrentThreadBound</a>.
isCurrentThreadBound :: MonadBase IO m => m Bool

-- | Generalized version of <a>runInBoundThread</a>.
runInBoundThread :: MonadBaseControl IO m => m a -> m a

-- | Generalized version of <a>runInUnboundThread</a>.
runInUnboundThread :: MonadBaseControl IO m => m a -> m a

-- | Generalized versio of <a>mkWeakThreadId</a>.
mkWeakThreadId :: MonadBase IO m => ThreadId -> m (Weak ThreadId)


-- | This is a wrapped version of <a>Data.IORef</a> with types generalised
--   from <a>IO</a> to all monads in <a>MonadBase</a>.
module Data.IORef.Lifted

-- | A mutable variable in the <a>IO</a> monad
data IORef a

-- | Generalized version of <a>newIORef</a>.
newIORef :: MonadBase IO m => a -> m (IORef a)

-- | Generalized version of <a>readIORef</a>.
readIORef :: MonadBase IO m => IORef a -> m a

-- | Generalized version of <a>writeIORef</a>.
writeIORef :: MonadBase IO m => IORef a -> a -> m ()

-- | Generalized version of <a>modifyIORef</a>.
modifyIORef :: MonadBase IO m => IORef a -> (a -> a) -> m ()

-- | Generalized version of <a>modifyIORef'</a>.
modifyIORef' :: MonadBase IO m => IORef a -> (a -> a) -> m ()

-- | Generalized version of <a>atomicModifyIORef</a>.
atomicModifyIORef :: MonadBase IO m => IORef a -> (a -> (a, b)) -> m b

-- | Generalized version of <a>atomicModifyIORef'</a>.
atomicModifyIORef' :: MonadBase IO m => IORef a -> (a -> (a, b)) -> m b

-- | Generalized version of <a>atomicWriteIORef</a>.
atomicWriteIORef :: MonadBase IO m => IORef a -> a -> m ()

-- | Generalized version of <a>mkWeakIORef</a>.
--   
--   Note any monadic side effects in <tt>m</tt> of the "finalizer"
--   computation are discarded.
mkWeakIORef :: MonadBaseControl IO m => IORef a -> m () -> m (Weak (IORef a))


-- | This is a wrapped version of <a>Foreign.Marshal.Utils</a> with types
--   generalized from <a>IO</a> to all monads in either <tt>MonadBase</tt>
--   or <a>MonadBaseControl</a>.
module Foreign.Marshal.Utils.Lifted

-- | Generalized version of <a>with</a>.
--   
--   Note, when the given function throws an exception any monadic side
--   effects in <tt>m</tt> will be discarded.
with :: (MonadBaseControl IO m, Storable a) => a -> (Ptr a -> m b) -> m b


-- | Attach a timeout event to monadic computations which are instances of
--   <a>MonadBaseControl</a>.
module System.Timeout.Lifted

-- | Generalized version of <a>timeout</a>.
--   
--   Note that when the given computation times out any side effects of
--   <tt>m</tt> are discarded. When the computation completes within the
--   given time the side-effects are restored on return.
timeout :: MonadBaseControl IO m => Int -> m a -> m (Maybe a)
