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


-- | Simple, IO-based library for Erlang-style thread supervision
--   
@package threads-supervisor
@version 1.0.2.0


-- | Use <tt>threads-supervisor</tt> if you want the "poor-man's Erlang
--   supervisors". <tt>threads-supervisor</tt> is an IO-based library with
--   minimal dependencies which does only one thing: It provides you a
--   <tt>Supervisor</tt> entity you can use to monitor your forked
--   computations. If one of the managed threads dies, you can decide if
--   and how to restart it. This gives you:
--   
--   <ul>
--   <li>Protection against silent exceptions which might terminate your
--   workers.</li>
--   <li>A simple but powerful way of structure your program into a
--   supervision tree, where the leaves are the worker threads, and the
--   nodes can be other supervisors being monitored.</li>
--   <li>A disaster recovery mechanism.</li>
--   </ul>
--   
--   You can install the <tt>threads-supervisor</tt> library by running:
--   &gt; $ cabal install threads-supervisor
module Control.Concurrent.Supervisor.Tutorial

module Control.Concurrent.Supervisor
type SupervisorSpec = Supervisor_ Uninitialised
type Supervisor = Supervisor_ Initialised
data DeadLetter
type RestartAction = ThreadId -> IO ThreadId
data SupervisionEvent
ChildBorn :: !ThreadId -> !UTCTime -> SupervisionEvent
ChildDied :: !ThreadId -> !SomeException -> !UTCTime -> SupervisionEvent
ChildRestarted :: !ThreadId -> !ThreadId -> !RestartStrategy -> !UTCTime -> SupervisionEvent
ChildFinished :: !ThreadId -> !UTCTime -> SupervisionEvent

-- | Erlang inspired strategies. At the moment only the <a>OneForOne</a> is
--   implemented.
data RestartStrategy
OneForOne :: RestartStrategy

-- | Creates a new <a>SupervisorSpec</a>. The reason it doesn't return a
--   <a>Supervisor</a> is to force you to call <tt>supervise</tt>
--   explicitly, in order to start the supervisor thread.
newSupervisorSpec :: IO SupervisorSpec
newSupervisor :: SupervisorSpec -> IO Supervisor

-- | Shutdown the given supervisor. This will cause the supervised children
--   to be killed as well. To do so, we explore the children tree, killing
--   workers as we go, and recursively calling <a>shutdownSupervisor</a> in
--   case we hit a monitored <a>Supervisor</a>.
shutdownSupervisor :: Supervisor -> IO ()

-- | Gives you access to the event this supervisor is generating, allowing
--   you to react. It's using a bounded queue to explicitly avoid memory
--   leaks in case you do not want to drain the queue to listen to incoming
--   events.
eventStream :: Supervisor -> TBQueue SupervisionEvent

-- | Returns the number of active threads at a given moment in time.
activeChildren :: Supervisor -> IO Int

-- | Fork a thread in a supervised mode.
forkSupervised :: Supervisor -> RestartStrategy -> IO () -> IO ThreadId

-- | Monitor another supervisor. To achieve these, we simulate a new
--   <a>DeadLetter</a>, so that the first supervisor will effectively
--   restart the monitored one. Thanks to the fact that for the supervisor
--   the restart means we just copy over its internal state, it should be
--   perfectly fine to do so.
monitor :: Supervisor -> Supervisor -> IO ()
instance Typeable MonitorRequest
instance Show RestartStrategy
instance Show SupervisionEvent
instance Show MonitorRequest
instance Exception MonitorRequest