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


-- | Spawn threads that never die (unless told to do so)
--   
--   A small library to create threads that never die. This is useful e.g.
--   for writing servers.
@package immortal
@version 0.2.2.1


-- | This module is designed to be imported qualified, e.g.
--   
--   <pre>
--   import qualified Control.Immortal as Immortal
--   </pre>
module Control.Immortal

-- | Immortal thread identifier (including its underlying <a>ThreadId</a>)
data Thread

-- | Spawn a new immortal thread running the given computation.
--   
--   If the computation ever finishes (either normally or due to an
--   exception), it will be restarted (in the same thread).
--   
--   The monadic «state» (captured by the <a>MonadBaseControl</a> instance)
--   will be preserved if the computation terminates normally, and reset
--   when the exception is thrown, so be cautious when <tt>m</tt> is
--   stateful. It is completely safe, however, to instantiate <tt>m</tt>
--   with something like <tt>ReaderT conf IO</tt> to pass configuration to
--   the new thread.
create :: MonadBaseControl IO m => (Thread -> m ()) -> m Thread

-- | Like <a>create</a>, but also apply the given label to the thread
--   (using <a>labelThread</a>).
createWithLabel :: MonadBaseControl IO m => String -> (Thread -> m ()) -> m Thread

-- | Make a thread mortal. Next time a mortal thread attempts to finish,
--   nothing will prevent it from doing so.
--   
--   Calling this on an already mortalized thread has no effect.
mortalize :: Thread -> IO ()

-- | If a thread was <a>mortalize</a>d, this will make it immortal again.
--   However, if it finished while being in the mortal state, it won't be
--   resurrected.
--   
--   Calling this on an immortal thread has no effect.
immortalize :: Thread -> IO ()

-- | Stop (kill) an immortal thread.
--   
--   This is equivalent to making it mortal, and then killing it with an
--   exception.
--   
--   Note that if the thread has installed its own exception handlers, it
--   may not be killed immediately.
stop :: Thread -> IO ()

-- | Wait for the thread to stop. Use <a>stop</a> to stop the thread
wait :: Thread -> IO ()

-- | An STM version of <a>wait</a>
waitSTM :: Thread -> STM ()

-- | Get the <a>ThreadId</a> of the immortal thread.
--   
--   The <a>ThreadId</a> can be used to throw asynchronous exception to
--   interrupt the computation. This won't kill the thread, however — even
--   if the exception is not handled, the computation will be simply
--   restarted.
threadId :: Thread -> ThreadId

-- | Run a callback every time the action finishes. This can be used e.g.
--   to log exceptions or attempts to exit when such attempts are not
--   expected. Example usage:
--   
--   <pre>
--   Immortal.create $ \_ -&gt; Immortal.onFinish print myAction
--   </pre>
--   
--   This is nothing more than a simple wrapper around <a>try</a>.
onFinish :: MonadBaseControl IO m => (Either SomeException () -> m ()) -> m () -> m ()

-- | Like <a>onFinish</a>, but the callback does not run when the thread is
--   mortalized (i.e. when the exit is expected).
--   
--   The <a>Thread</a> argument is used to find out the mortality of the
--   thread.
onUnexpectedFinish :: MonadBaseControl IO m => Thread -> (Either SomeException () -> m ()) -> m () -> m ()
