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


-- | 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
data SupervisionCtx q
data Supervisor q
class QueueLike q
newQueueIO :: QueueLike q => Natural -> IO (q a)
readQueue :: QueueLike q => q a -> STM a
writeQueue :: QueueLike q => q a -> a -> STM ()
data Child_ q
data DeadLetter
type RestartAction = ThreadId -> IO ThreadId
data SupervisionEvent
ChildBorn :: !ThreadId -> !UTCTime -> SupervisionEvent
ChildDied :: !ThreadId -> !SomeException -> !UTCTime -> SupervisionEvent
ChildRestarted :: !ThreadId -> !ThreadId -> !RetryStatus -> !UTCTime -> SupervisionEvent
ChildNotFound :: !ThreadId -> !UTCTime -> SupervisionEvent
StaleDeadLetterReceived :: !ThreadId -> !LetterEpoch -> !ChildEpoch -> !UTCTime -> SupervisionEvent
ChildRestartLimitReached :: !ThreadId -> !RetryStatus -> !UTCTime -> SupervisionEvent
ChildFinished :: !ThreadId -> !UTCTime -> SupervisionEvent

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

-- | The supervised <a>Child_</a> was restarted successfully.
Restarted :: !ThreadId -> !ThreadId -> !RetryStatus -> !UTCTime -> RestartResult

-- | A stale <a>DeadLetter</a> was received.
StaleDeadLetter :: !ThreadId -> !LetterEpoch -> !ChildEpoch -> !UTCTime -> RestartResult

-- | The restart failed for a reason decribed by a <a>SupervisionEvent</a>
RestartFailed :: SupervisionEvent -> RestartResult
newSupervisor :: QueueLike q => RestartStrategy -> Natural -> IO (Supervisor q)

-- | Smart constructor which offers a default throttling based on fibonacci
--   numbers.
fibonacciRetryPolicy :: RetryPolicyM IO

-- | 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 :: QueueLike q => Supervisor 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 => Supervisor q -> q SupervisionEvent

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

-- | Fork a thread in a supervised mode.
forkSupervised :: QueueLike q => Supervisor q -> RetryPolicyM IO -> 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. Returns the <a>ThreadId</a> of the monitored
--   supervisor.
monitorWith :: QueueLike q => RetryPolicyM IO -> Supervisor q -> Supervisor q -> IO ThreadId
instance GHC.Show.Show Control.Concurrent.Supervisor.Types.LetterEpoch
instance GHC.Show.Show Control.Concurrent.Supervisor.Types.ChildEpoch
instance GHC.Show.Show Control.Concurrent.Supervisor.Types.SupervisionEvent
instance GHC.Show.Show Control.Concurrent.Supervisor.Types.RestartResult
instance GHC.Show.Show Control.Concurrent.Supervisor.Types.RestartStrategy
instance Control.Concurrent.Supervisor.Types.QueueLike Control.Concurrent.STM.TQueue.TQueue
instance Control.Concurrent.Supervisor.Types.QueueLike Control.Concurrent.STM.TBQueue.TBQueue


-- | 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 Supervisor = Supervisor TBQueue
type Child = Child_ TBQueue
newSupervisor :: RestartStrategy -> Natural -> IO Supervisor

-- | The default size of the queue where <a>SupervisionEvent</a>(s) are
--   written.
defaultEventQueueSize :: Natural

-- | Erlang inspired strategies. At the moment only the <a>OneForOne</a> is
--   implemented.
data RestartStrategy
OneForOne :: RestartStrategy
data SupervisionEvent
ChildBorn :: !ThreadId -> !UTCTime -> SupervisionEvent
ChildDied :: !ThreadId -> !SomeException -> !UTCTime -> SupervisionEvent
ChildRestarted :: !ThreadId -> !ThreadId -> !RetryStatus -> !UTCTime -> SupervisionEvent
ChildNotFound :: !ThreadId -> !UTCTime -> SupervisionEvent
StaleDeadLetterReceived :: !ThreadId -> !LetterEpoch -> !ChildEpoch -> !UTCTime -> SupervisionEvent
ChildRestartLimitReached :: !ThreadId -> !RetryStatus -> !UTCTime -> SupervisionEvent
ChildFinished :: !ThreadId -> !UTCTime -> SupervisionEvent
type RestartAction = ThreadId -> IO ThreadId
data Child_ q
data RestartResult

-- | The supervised <a>Child_</a> was restarted successfully.
Restarted :: !ThreadId -> !ThreadId -> !RetryStatus -> !UTCTime -> RestartResult

-- | A stale <a>DeadLetter</a> was received.
StaleDeadLetter :: !ThreadId -> !LetterEpoch -> !ChildEpoch -> !UTCTime -> RestartResult

-- | The restart failed for a reason decribed by a <a>SupervisionEvent</a>
RestartFailed :: SupervisionEvent -> RestartResult
data DeadLetter
class QueueLike q
newQueueIO :: QueueLike q => Natural -> IO (q a)
readQueue :: QueueLike q => q a -> STM a
writeQueue :: QueueLike q => q a -> a -> STM ()
data SupervisionCtx q

-- | Smart constructor which offers a default throttling based on fibonacci
--   numbers.
fibonacciRetryPolicy :: RetryPolicyM 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 => Supervisor q -> q SupervisionEvent

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

-- | 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 :: QueueLike q => Supervisor q -> IO ()

-- | Fork a thread in a supervised mode.
forkSupervised :: QueueLike q => Supervisor q -> RetryPolicyM IO -> 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. Returns the <a>ThreadId</a> of the monitored
--   supervisor.
monitorWith :: QueueLike q => RetryPolicyM IO -> Supervisor q -> Supervisor q -> IO ThreadId

module Control.Concurrent.Supervisor
type Supervisor = Supervisor TQueue
type Child = Child_ TQueue
newSupervisor :: RestartStrategy -> IO Supervisor

-- | Erlang inspired strategies. At the moment only the <a>OneForOne</a> is
--   implemented.
data RestartStrategy
OneForOne :: RestartStrategy
data SupervisionEvent
ChildBorn :: !ThreadId -> !UTCTime -> SupervisionEvent
ChildDied :: !ThreadId -> !SomeException -> !UTCTime -> SupervisionEvent
ChildRestarted :: !ThreadId -> !ThreadId -> !RetryStatus -> !UTCTime -> SupervisionEvent
ChildNotFound :: !ThreadId -> !UTCTime -> SupervisionEvent
StaleDeadLetterReceived :: !ThreadId -> !LetterEpoch -> !ChildEpoch -> !UTCTime -> SupervisionEvent
ChildRestartLimitReached :: !ThreadId -> !RetryStatus -> !UTCTime -> SupervisionEvent
ChildFinished :: !ThreadId -> !UTCTime -> SupervisionEvent
type RestartAction = ThreadId -> IO ThreadId
data Child_ q
data RestartResult

-- | The supervised <a>Child_</a> was restarted successfully.
Restarted :: !ThreadId -> !ThreadId -> !RetryStatus -> !UTCTime -> RestartResult

-- | A stale <a>DeadLetter</a> was received.
StaleDeadLetter :: !ThreadId -> !LetterEpoch -> !ChildEpoch -> !UTCTime -> RestartResult

-- | The restart failed for a reason decribed by a <a>SupervisionEvent</a>
RestartFailed :: SupervisionEvent -> RestartResult
data DeadLetter
class QueueLike q
newQueueIO :: QueueLike q => Natural -> IO (q a)
readQueue :: QueueLike q => q a -> STM a
writeQueue :: QueueLike q => q a -> a -> STM ()
data SupervisionCtx q

-- | Smart constructor which offers a default throttling based on fibonacci
--   numbers.
fibonacciRetryPolicy :: RetryPolicyM 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 => Supervisor q -> q SupervisionEvent

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

-- | 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 :: QueueLike q => Supervisor q -> IO ()

-- | Fork a thread in a supervised mode.
forkSupervised :: QueueLike q => Supervisor q -> RetryPolicyM IO -> 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. Returns the <a>ThreadId</a> of the monitored
--   supervisor.
monitorWith :: QueueLike q => RetryPolicyM IO -> Supervisor q -> Supervisor q -> IO ThreadId