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


-- | Simple, IO-based library for Erlang-style thread supervision
--   
--   Simple, IO-based library for Erlang-style thread supervision
@package threads-supervisor
@version 1.0.4.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.Types
type SupervisorSpec0 q = Supervisor_ q Uninitialised
type Supervisor0 q = Supervisor_ q Initialised
data Child_ q
data DeadLetter
type RestartAction = ThreadId -> IO ThreadId
data SupervisionEvent
ChildBorn :: !ThreadId -> !UTCTime -> SupervisionEvent
ChildDied :: !ThreadId -> !SomeException -> !UTCTime -> SupervisionEvent
ChildRestarted :: !ThreadId -> !ThreadId -> !RestartStrategy -> !UTCTime -> SupervisionEvent
ChildRestartLimitReached :: !ThreadId -> !RestartStrategy -> !UTCTime -> SupervisionEvent
ChildFinished :: !ThreadId -> !UTCTime -> SupervisionEvent

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

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

-- | Smart constructor which offers a default throttling based on fibonacci
--   numbers.
oneForOne :: RestartStrategy

-- | 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 <tt>Supervisor</tt>.
shutdownSupervisor :: QueueLike q => Supervisor0 q -> 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 :: QueueLike q => Supervisor0 q -> q SupervisionEvent

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

-- | Fork a thread in a supervised mode.
forkSupervised :: QueueLike q => Supervisor0 q -> 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 :: QueueLike q => Supervisor0 q -> Supervisor0 q -> IO ()
instance GHC.Show.Show Control.Concurrent.Supervisor.Types.MonitorRequest
instance GHC.Show.Show Control.Concurrent.Supervisor.Types.SupervisionEvent
instance Control.Concurrent.Supervisor.Types.QueueLike Control.Concurrent.STM.TQueue.TQueue
instance Control.Concurrent.Supervisor.Types.QueueLike Control.Concurrent.STM.TBQueue.TBQueue
instance GHC.Show.Show Control.Concurrent.Supervisor.Types.RestartStrategy
instance GHC.Exception.Exception Control.Concurrent.Supervisor.Types.MonitorRequest


-- | This module offers a <a>Bounded</a> supervisor variant, where
--   <a>SupervisionEvent</a>(s) are written on a <a>TBQueue</a>, and simply
--   discarded if the queue is full.
module Control.Concurrent.Supervisor.Bounded
type SupervisorSpec = SupervisorSpec0 TBQueue
type Supervisor = Supervisor0 TBQueue
type Child = Child_ TBQueue

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

-- | Like <a>newSupervisorSpec</a>, but give the user control over the size
--   of the event queue.
newSupervisorSpecBounded :: Int -> IO SupervisorSpec
newSupervisor :: SupervisorSpec -> IO Supervisor

module Control.Concurrent.Supervisor
type SupervisorSpec = SupervisorSpec0 TQueue
type Supervisor = Supervisor0 TQueue
type Child = Child_ TQueue

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