-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Supervisors for The Cloud Haskell Application Platform -- -- A part of the Cloud Haskell framework This package implements a -- process which supervises a set of other processes, referred to as its -- children. These child processes can be either workers (i.e., processes -- that do something useful in your application) or other supervisors. In -- this way, supervisors may be used to build a hierarchical process -- structure called a supervision tree, which provides a convenient -- structure for building fault tolerant software. For detailed -- information see Control.Distributed.Process.Supervisor @package distributed-process-supervisor @version 0.1.3.2 -- | This module implements a process which supervises a set of other -- processes, referred to as its children. These child processes -- can be either workers (i.e., processes that do something useful in -- your application) or other supervisors. In this way, supervisors may -- be used to build a hierarchical process structure called a supervision -- tree, which provides a convenient structure for building fault -- tolerant software. -- -- Unless otherwise stated, all functions in this module will cause the -- calling process to exit unless the specified supervisor process -- exists. -- -- -- -- A supervisor is responsible for starting, stopping and monitoring its -- child processes so as to keep them alive by restarting them when -- necessary. -- -- The supervisors children are defined as a list of child specifications -- (see ChildSpec). When a supervisor is started, its children are -- started in left-to-right (insertion order) according to this list. -- When a supervisor stops (or exits for any reason), it will terminate -- its children in reverse (i.e., from right-to-left of insertion) order. -- Child specs can be added to the supervisor after it has started, -- either on the left or right of the existing list of children. -- -- When the supervisor spawns its child processes, they are always linked -- to their parent (i.e., the supervisor), therefore even if the -- supervisor is terminated abruptly by an asynchronous exception, the -- children will still be taken down with it, though somewhat less -- ceremoniously in that case. -- -- -- -- Supervisors are initialised with a RestartStrategy, which -- describes how the supervisor should respond to a child that exits and -- should be restarted (see below for the rules governing child restart -- eligibility). Each restart strategy comprises a RestartMode and -- RestartLimit, which govern how the restart should be handled, -- and the point at which the supervisor should give up and terminate -- itself respectively. -- -- With the exception of the RestartOne strategy, which -- indicates that the supervisor will restart only the one -- individual failing child, each strategy describes a way to select the -- set of children that should be restarted if any child fails. -- The RestartAll strategy, as its name suggests, selects -- all children, whilst the RestartLeft and -- RestartRight strategies select all children to the -- left or right of the failed child, in insertion (i.e., startup) order. -- -- Note that a branch restart will only occur if the child that -- exited is meant to be restarted. Since Temporary children are -- never restarted and Transient children are not -- restarted if they exit normally, in both these circumstances we leave -- the remaining supervised children alone. Otherwise, the failing child -- is always included in the branch to be restarted. -- -- For a hypothetical set of children a through d, the -- following pseudocode demonstrates how the restart strategies work. -- -- 
--   let children = [a..d]
--   let failure = c
--   restartsFor RestartOne   children failure = [c]
--   restartsFor RestartAll   children failure = [a,b,c,d]
--   restartsFor RestartLeft  children failure = [a,b,c]
--   restartsFor RestartRight children failure = [c,d]
--
-- -- -- -- We refer to a restart (strategy) that involves a set of children as a -- branch restart from now on. The behaviour of branch restarts -- can be further refined by the RestartMode with which a -- RestartStrategy is parameterised. The RestartEach mode -- treats each child sequentially, first stopping the respective child -- process and then restarting it. Each child is stopped and started -- fully before moving on to the next, as the following imaginary example -- demonstrates for children [a,b,c]: -- -- 
--   stop  a
--   start a
--   stop  b
--   start b
--   stop  c
--   start c
--
-- -- By contrast, RestartInOrder will first run through the -- selected list of children, stopping them. Then, once all the children -- have been stopped, it will make a second pass, to handle (re)starting -- them. No child is started until all children have been stopped, as the -- following imaginary example demonstrates: -- -- 
--   stop  a
--   stop  b
--   stop  c
--   start a
--   start b
--   start c
--
-- -- Both the previous examples have shown children being stopped and -- started from left to right, but that is up to the user. The -- RestartMode data type's constructors take a -- RestartOrder, which determines whether the selected children -- will be processed from LeftToRight or RightToLeft. -- -- Sometimes it is desireable to stop children in one order and start -- them in the opposite. This is typically the case when children are in -- some way dependent on one another, such that restarting them in the -- wrong order might cause the system to misbehave. For this scenarios, -- there is another RestartMode that will shut children down in -- the given order, but then restarts them in the reverse. Using -- RestartRevOrder mode, if we have children [a,b,c] -- such that b depends on a and c on -- b, we can stop them in the reverse of their startup order, -- but restart them the other way around like so: -- -- 
--   RestartRevOrder RightToLeft
--
-- -- The effect will be thus: -- -- 
--   stop  c
--   stop  b
--   stop  a
--   start a
--   start b
--   start c
--
-- -- -- -- If a child process repeatedly crashes during (or shortly after) -- starting, it is possible for the supervisor to get stuck in an endless -- loop of restarts. In order prevent this, each restart strategy is -- parameterised with a RestartLimit that caps the number of -- restarts allowed within a specific time period. If the supervisor -- exceeds this limit, it will stop, terminating all its children (in -- left-to-right order) and exit with the reason ExitOther -- ReachedMaxRestartIntensity. -- -- The MaxRestarts type is a positive integer, and together with a -- specified TimeInterval forms the RestartLimit to which -- the supervisor will adhere. Since a great many children can be -- restarted in close succession when a branch restart occurs (as -- a result of RestartAll, RestartLeft or -- RestartRight being triggered), the supervisor will track the -- operation as a single restart attempt, since otherwise it would likely -- exceed its maximum restart intensity too quickly. -- -- -- -- When the supervisor detects that a child has died, the -- RestartPolicy configured in the child specification is used to -- determin what to do. If the this is set to Permanent, then -- the child is always restarted. If it is Temporary, then the -- child is never restarted and the child specification is removed from -- the supervisor. A Transient child will be restarted only if -- it terminates abnormally, otherwise it is left inactive (but -- its specification is left in place). Finally, an Intrinsic -- child is treated like a Transient one, except that if -- this kind of child exits normally, then the supervisor -- will also exit normally. -- -- When the supervisor does terminate a child, the -- ChildTerminationPolicy provided with the ChildSpec -- determines how the supervisor should go about doing so. If this is -- TerminateImmediately, then the child will be killed without -- further notice, which means the child will not have an -- opportunity to clean up any internal state and/or release any held -- resources. If the policy is TerminateTimeout delay however, -- the child will be sent an exit signal instead, i.e., the -- supervisor will cause the child to exit via exit childPid -- ExitShutdown, and then will wait until the given delay -- for the child to exit normally. If this does not happen within the -- given delay, the supervisor will revert to the more aggressive -- TerminateImmediately policy and try again. Any errors that -- occur during a timed-out shutdown will be logged, however exit reasons -- resulting from TerminateImmediately are ignored. -- -- -- -- The ToChildStart typeclass simplifies the process of defining a -- ChildStart providing three default instances from which a -- ChildStart datum can be generated. The first, takes a -- Closure (Process ()), where the enclosed action (in the -- Process monad) is the actual (long running) code that we wish -- to supervise. In the case of a managed process, this is usually -- the server loop, constructed by evaluating some variant of -- ManagedProcess.serve. -- -- The other two instances provide a means for starting children without -- having to provide a Closure. Both instances wrap the supplied -- Process action in some necessary boilerplate code, which -- handles spawning a new process and communicating its -- ProcessId to the supervisor. The instance for Addressable -- a => SupervisorPid -> Process a is special however, since -- this API is intended for uses where the typical interactions with a -- process take place via an opaque handle, for which an instance of the -- Addressable typeclass is provided. This latter approach -- requires the expression which is responsible for yielding the -- Addressable handle to handling linking the target process -- with the supervisor, since we have delegated responsibility for -- spawning the new process and cannot perform the link oepration -- ourselves. -- -- -- -- To create a supervision tree, one simply adds supervisors below one -- another as children, setting the childType field of their -- ChildSpec to Supervisor instead of Worker. -- Supervision tree can be arbitrarilly deep, and it is for this reason -- that we recommend giving a Supervisor child an arbitrary -- length of time to stop, by setting the delay to Infinity or a -- very large TimeInterval. module Control.Distributed.Process.Supervisor -- | Specification for a child process. The child must be uniquely -- identified by it's childKey within the supervisor. The -- supervisor will start the child itself, therefore childRun -- should contain the child process' implementation e.g., if the child is -- a long running server, this would be the server loop, as with -- e.g., ManagedProces.start. data ChildSpec ChildSpec :: !ChildKey -> !ChildType -> !RestartPolicy -> !ChildTerminationPolicy -> !ChildStart -> !(Maybe RegisteredName) -> ChildSpec [childKey] :: ChildSpec -> !ChildKey [childType] :: ChildSpec -> !ChildType [childRestart] :: ChildSpec -> !RestartPolicy [childStop] :: ChildSpec -> !ChildTerminationPolicy [childStart] :: ChildSpec -> !ChildStart [childRegName] :: ChildSpec -> !(Maybe RegisteredName) -- | Identifies a child process by name. type ChildKey = String -- | Specifies whether the child is another supervisor, or a worker. data ChildType Worker :: ChildType Supervisor :: ChildType data ChildTerminationPolicy TerminateTimeout :: !Delay -> ChildTerminationPolicy TerminateImmediately :: ChildTerminationPolicy data ChildStart RunClosure :: !(Closure (Process ())) -> ChildStart CreateHandle :: !(Closure (SupervisorPid -> Process (ChildPid, Message))) -> ChildStart StarterProcess :: !StarterPid -> ChildStart data RegisteredName LocalName :: !String -> RegisteredName CustomRegister :: !(Closure (ChildPid -> Process ())) -> RegisteredName -- | Describes when a terminated child process should be restarted. data RestartPolicy -- | a permanent child will always be restarted Permanent :: RestartPolicy -- | a temporary child will never be restarted Temporary :: RestartPolicy -- | A transient child will be restarted only if it terminates abnormally Transient :: RestartPolicy -- | as Transient, but if the child exits normally, the supervisor -- also exits normally Intrinsic :: RestartPolicy -- | A reference to a (possibly running) child. data ChildRef -- | a reference to the (currently running) child ChildRunning :: !ChildPid -> ChildRef -- | also a currently running child, with extra child info ChildRunningExtra :: !ChildPid -> !Message -> ChildRef -- | a reference to the old (previous) child (now restarting) ChildRestarting :: !ChildPid -> ChildRef -- | indicates the child is not currently running ChildStopped :: ChildRef -- | a non-temporary child exited with ChildInitIgnore ChildStartIgnored :: ChildRef isRunning :: ChildRef -> Bool isRestarting :: ChildRef -> Bool type Child = (ChildRef, ChildSpec) -- | Static labels (in the remote table) are strings. type StaticLabel = String type SupervisorPid = ProcessId type ChildPid = ProcessId type StarterPid = ProcessId -- | A type that can be converted to a ChildStart. class ToChildStart a toChildStart :: ToChildStart a => a -> Process ChildStart -- | Start a supervisor (process), running the supplied children and -- restart strategy. -- -- 
--   start = spawnLocal . run
--
start :: RestartStrategy -> ShutdownMode -> [ChildSpec] -> Process SupervisorPid -- | Run the supplied children using the provided restart strategy. run :: RestartStrategy -> ShutdownMode -> [ChildSpec] -> Process () data MaxRestarts -- | Smart constructor for MaxRestarts. The maximum restart count -- must be a positive integer. maxRestarts :: Int -> MaxRestarts -- | A compulsary limit on the number of restarts that a supervisor will -- tolerate before it terminates all child processes and then itself. If -- > MaxRestarts occur within the specified -- TimeInterval, termination will occur. This prevents the -- supervisor from entering an infinite loop of child process -- terminations and restarts. data RestartLimit RestartLimit :: !MaxRestarts -> !TimeInterval -> RestartLimit [maxR] :: RestartLimit -> !MaxRestarts [maxT] :: RestartLimit -> !TimeInterval limit :: MaxRestarts -> TimeInterval -> RestartLimit defaultLimits :: RestartLimit data RestartMode -- | stop then start each child sequentially, i.e., foldlM -- stopThenStart children RestartEach :: !RestartOrder -> RestartMode [order] :: RestartMode -> !RestartOrder -- | stop all children first, then restart them sequentially RestartInOrder :: !RestartOrder -> RestartMode [order] :: RestartMode -> !RestartOrder -- | stop all children in the given order, but start them in reverse RestartRevOrder :: !RestartOrder -> RestartMode [order] :: RestartMode -> !RestartOrder data RestartOrder LeftToRight :: RestartOrder RightToLeft :: RestartOrder -- | Strategy used by a supervisor to handle child restarts, whether due to -- unexpected child failure or explicit restart requests from a client. -- -- Some terminology: We refer to child processes managed by the same -- supervisor as siblings. When restarting a child process, the -- RestartNone policy indicates that sibling processes should be -- left alone, whilst the RestartAll policy will cause all -- children to be restarted (in the same order they were started). -- -- The other two restart strategies refer to prior and -- subsequent siblings, which describe's those children's -- configured position (i.e., insertion order). These latter modes allow -- one to control the order in which siblings are restarted, and to -- exclude some siblings from the restart without having to resort to -- grouping them using a child supervisor. data RestartStrategy -- | restart only the failed child process RestartOne :: !RestartLimit -> RestartStrategy [intensity] :: RestartStrategy -> !RestartLimit -- | also restart all siblings RestartAll :: !RestartLimit -> !RestartMode -> RestartStrategy [intensity] :: RestartStrategy -> !RestartLimit [mode] :: RestartStrategy -> !RestartMode -- | restart prior siblings (i.e., prior start order) RestartLeft :: !RestartLimit -> !RestartMode -> RestartStrategy [intensity] :: RestartStrategy -> !RestartLimit [mode] :: RestartStrategy -> !RestartMode -- | restart subsequent siblings (i.e., subsequent start order) RestartRight :: !RestartLimit -> !RestartMode -> RestartStrategy [intensity] :: RestartStrategy -> !RestartLimit [mode] :: RestartStrategy -> !RestartMode data ShutdownMode SequentialShutdown :: !RestartOrder -> ShutdownMode ParallelShutdown :: ShutdownMode -- | Provides a default RestartStrategy for RestartOne. -- > restartOne = RestartOne defaultLimits restartOne :: RestartStrategy -- | Provides a default RestartStrategy for RestartAll. -- > restartOne = RestartAll defaultLimits (RestartEach LeftToRight) restartAll :: RestartStrategy -- | Provides a default RestartStrategy for RestartLeft. -- > restartOne = RestartLeft defaultLimits (RestartEach LeftToRight) restartLeft :: RestartStrategy -- | Provides a default RestartStrategy for RestartRight. -- > restartOne = RestartRight defaultLimits (RestartEach LeftToRight) restartRight :: RestartStrategy -- | Add a new child. addChild :: Addressable a => a -> ChildSpec -> Process AddChildResult data AddChildResult ChildAdded :: !ChildRef -> AddChildResult ChildFailedToStart :: !StartFailure -> AddChildResult data StartChildResult ChildStartOk :: !ChildRef -> StartChildResult ChildStartFailed :: !StartFailure -> StartChildResult ChildStartUnknownId :: StartChildResult ChildStartInitIgnored :: StartChildResult -- | Start an existing (configured) child. The ChildSpec must -- already be present (see addChild), otherwise the operation will -- fail. startChild :: Addressable a => a -> ChildKey -> Process StartChildResult -- | Atomically add and start a new child spec. Will fail if a child with -- the given key is already present. startNewChild :: Addressable a => a -> ChildSpec -> Process AddChildResult -- | Terminate a running child. terminateChild :: Addressable a => a -> ChildKey -> Process TerminateChildResult data TerminateChildResult TerminateChildOk :: TerminateChildResult TerminateChildUnknownId :: TerminateChildResult -- | Delete a supervised child. The child must already be stopped (see -- terminateChild). deleteChild :: Addressable a => a -> ChildKey -> Process DeleteChildResult -- | The result of a call to removeChild. data DeleteChildResult -- | the child specification was successfully removed ChildDeleted :: DeleteChildResult -- | the child specification was not found ChildNotFound :: DeleteChildResult -- | the child was not removed, as it was not stopped. ChildNotStopped :: !ChildRef -> DeleteChildResult -- | Forcibly restart a running child. restartChild :: Addressable a => a -> ChildKey -> Process RestartChildResult data RestartChildResult ChildRestartOk :: !ChildRef -> RestartChildResult ChildRestartFailed :: !StartFailure -> RestartChildResult ChildRestartUnknownId :: RestartChildResult ChildRestartIgnored :: RestartChildResult -- | Gracefully terminate a running supervisor. Returns immediately if the -- address cannot be resolved. shutdown :: Resolvable a => a -> Process () -- | As shutdown, but waits until the supervisor process has exited, -- at which point the caller can be sure that all children have also -- stopped. Returns immediately if the address cannot be resolved. shutdownAndWait :: Resolvable a => a -> Process () -- | Lookup a possibly supervised child, given its ChildKey. lookupChild :: Addressable a => a -> ChildKey -> Process (Maybe (ChildRef, ChildSpec)) -- | List all know (i.e., configured) children. listChildren :: Addressable a => a -> Process [Child] data SupervisorStats SupervisorStats :: Int -> Int -> Int -> Int -> Int -> Int -> Int -> SupervisorStats [_children] :: SupervisorStats -> Int [_supervisors] :: SupervisorStats -> Int [_workers] :: SupervisorStats -> Int [_running] :: SupervisorStats -> Int [_activeSupervisors] :: SupervisorStats -> Int [_activeWorkers] :: SupervisorStats -> Int [totalRestarts] :: SupervisorStats -> Int -- | Obtain statistics about a running supervisor. statistics :: Addressable a => a -> Process (SupervisorStats) -- | Provides failure information when (re-)start failure is indicated. data StartFailure -- | a child with this ChildKey already exists StartFailureDuplicateChild :: !ChildRef -> StartFailure -- | the child is already up and running StartFailureAlreadyRunning :: !ChildRef -> StartFailure -- | a closure cannot be resolved StartFailureBadClosure :: !StaticLabel -> StartFailure -- | a child died (almost) immediately on starting StartFailureDied :: !DiedReason -> StartFailure data ChildInitFailure ChildInitFailure :: !String -> ChildInitFailure ChildInitIgnore :: ChildInitFailure instance GHC.Generics.Constructor Control.Distributed.Process.Supervisor.C1_0IgnoreChildReq instance GHC.Generics.Datatype Control.Distributed.Process.Supervisor.D1IgnoreChildReq instance GHC.Generics.Constructor Control.Distributed.Process.Supervisor.C1_0TerminateChildReq instance GHC.Generics.Datatype Control.Distributed.Process.Supervisor.D1TerminateChildReq instance GHC.Generics.Constructor Control.Distributed.Process.Supervisor.C1_0RestartChildReq instance GHC.Generics.Datatype Control.Distributed.Process.Supervisor.D1RestartChildReq instance GHC.Generics.Constructor Control.Distributed.Process.Supervisor.C1_0StartChildReq instance GHC.Generics.Datatype Control.Distributed.Process.Supervisor.D1StartChildReq instance GHC.Generics.Constructor Control.Distributed.Process.Supervisor.C1_0AddChildReq instance GHC.Generics.Datatype Control.Distributed.Process.Supervisor.D1AddChildReq instance GHC.Generics.Constructor Control.Distributed.Process.Supervisor.C1_0ListReq instance GHC.Generics.Datatype Control.Distributed.Process.Supervisor.D1ListReq instance GHC.Generics.Constructor Control.Distributed.Process.Supervisor.C1_0StatsReq instance GHC.Generics.Datatype Control.Distributed.Process.Supervisor.D1StatsReq instance GHC.Generics.Constructor Control.Distributed.Process.Supervisor.C1_0FindReq instance GHC.Generics.Datatype Control.Distributed.Process.Supervisor.D1FindReq instance GHC.Generics.Constructor Control.Distributed.Process.Supervisor.C1_0DeleteChild instance GHC.Generics.Datatype Control.Distributed.Process.Supervisor.D1DeleteChild instance GHC.Generics.Generic Control.Distributed.Process.Supervisor.IgnoreChildReq instance GHC.Classes.Eq Control.Distributed.Process.Supervisor.TerminateChildReq instance GHC.Show.Show Control.Distributed.Process.Supervisor.TerminateChildReq instance GHC.Generics.Generic Control.Distributed.Process.Supervisor.TerminateChildReq instance GHC.Classes.Eq Control.Distributed.Process.Supervisor.RestartChildReq instance GHC.Show.Show Control.Distributed.Process.Supervisor.RestartChildReq instance GHC.Generics.Generic Control.Distributed.Process.Supervisor.RestartChildReq instance GHC.Generics.Generic Control.Distributed.Process.Supervisor.StartChildReq instance GHC.Show.Show Control.Distributed.Process.Supervisor.AddChildReq instance GHC.Generics.Generic Control.Distributed.Process.Supervisor.AddChildReq instance GHC.Generics.Generic Control.Distributed.Process.Supervisor.ListReq instance GHC.Generics.Generic Control.Distributed.Process.Supervisor.StatsReq instance GHC.Generics.Generic Control.Distributed.Process.Supervisor.FindReq instance GHC.Generics.Generic Control.Distributed.Process.Supervisor.DeleteChild instance Control.Distributed.Process.Supervisor.ToChildStart (Control.Distributed.Static.Closure (Control.Distributed.Process.Internal.Types.Process ())) instance Control.Distributed.Process.Supervisor.ToChildStart (Control.Distributed.Static.Closure (Control.Distributed.Process.Supervisor.Types.SupervisorPid -> Control.Distributed.Process.Internal.Types.Process (Control.Distributed.Process.Supervisor.Types.ChildPid, Control.Distributed.Process.Internal.Types.Message))) instance Control.Distributed.Process.Supervisor.ToChildStart (Control.Distributed.Process.Internal.Types.Process ()) instance Control.Distributed.Process.Extras.Internal.Types.Resolvable a => Control.Distributed.Process.Supervisor.ToChildStart (Control.Distributed.Process.Supervisor.Types.SupervisorPid -> Control.Distributed.Process.Internal.Types.Process a) instance Data.Binary.Class.Binary Control.Distributed.Process.Supervisor.DeleteChild instance Control.DeepSeq.NFData Control.Distributed.Process.Supervisor.DeleteChild instance Data.Binary.Class.Binary Control.Distributed.Process.Supervisor.FindReq instance Control.DeepSeq.NFData Control.Distributed.Process.Supervisor.FindReq instance Data.Binary.Class.Binary Control.Distributed.Process.Supervisor.StatsReq instance Control.DeepSeq.NFData Control.Distributed.Process.Supervisor.StatsReq instance Data.Binary.Class.Binary Control.Distributed.Process.Supervisor.ListReq instance Control.DeepSeq.NFData Control.Distributed.Process.Supervisor.ListReq instance Data.Binary.Class.Binary Control.Distributed.Process.Supervisor.AddChildReq instance Control.DeepSeq.NFData Control.Distributed.Process.Supervisor.AddChildReq instance Data.Binary.Class.Binary Control.Distributed.Process.Supervisor.StartChildReq instance Control.DeepSeq.NFData Control.Distributed.Process.Supervisor.StartChildReq instance Data.Binary.Class.Binary Control.Distributed.Process.Supervisor.RestartChildReq instance Control.DeepSeq.NFData Control.Distributed.Process.Supervisor.RestartChildReq instance Data.Binary.Class.Binary Control.Distributed.Process.Supervisor.TerminateChildReq instance Control.DeepSeq.NFData Control.Distributed.Process.Supervisor.TerminateChildReq instance Data.Binary.Class.Binary Control.Distributed.Process.Supervisor.IgnoreChildReq instance Control.DeepSeq.NFData Control.Distributed.Process.Supervisor.IgnoreChildReq instance Control.Distributed.Process.Extras.SystemLog.Logger Control.Distributed.Process.Supervisor.LogSink