-- 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.2.3 module Control.Distributed.Process.Supervisor.Management -- | The MxAgentId for the node monitoring agent. supervisionAgentId :: MxAgentId -- | Starts the supervision monitoring agent. supervisionMonitor :: Process ProcessId -- | Monitor the supervisor for the given pid. Binds a typed channel to the -- calling process, to which the resulting ReceivePort belongs. -- -- Multiple monitors can be created for any calling process - -- sup pair. Each monitor maintains its own typed channel, which -- will only contain MxSupervisor entries obtained after -- the channel was established. monitorSupervisor :: SupervisorPid -> Process (ReceivePort MxSupervisor) -- | Removes all monitors for sup, associated with the calling -- process. It is not possible to delete individual monitors (i.e. typed -- channels). unmonitorSupervisor :: SupervisorPid -> Process () -- | Supervisor event data published to the management API data MxSupervisor -- | A branch restart took place SupervisorBranchRestarted :: SupervisorPid -> ChildKey -> DiedReason -> RestartStrategy -> MxSupervisor [supervisorPid] :: MxSupervisor -> SupervisorPid [childSpecKey] :: MxSupervisor -> ChildKey [diedReason] :: MxSupervisor -> DiedReason [branchStrategy] :: MxSupervisor -> RestartStrategy -- | A child is being restarted SupervisedChildRestarting :: SupervisorPid -> Maybe ChildPid -> ChildKey -> ExitReason -> MxSupervisor [supervisorPid] :: MxSupervisor -> SupervisorPid [childInScope] :: MxSupervisor -> Maybe ChildPid [childSpecKey] :: MxSupervisor -> ChildKey [exitReason] :: MxSupervisor -> ExitReason -- | A child has been started SupervisedChildStarted :: SupervisorPid -> ChildRef -> ChildKey -> MxSupervisor [supervisorPid] :: MxSupervisor -> SupervisorPid [childRef] :: MxSupervisor -> ChildRef [childSpecKey] :: MxSupervisor -> ChildKey -- | A child failed to start SupervisedChildStartFailure :: SupervisorPid -> StartFailure -> ChildKey -> MxSupervisor [supervisorPid] :: MxSupervisor -> SupervisorPid [startFailure] :: MxSupervisor -> StartFailure [childSpecKey] :: MxSupervisor -> ChildKey -- | A child process death was detected SupervisedChildDied :: SupervisorPid -> ChildPid -> ExitReason -> MxSupervisor [supervisorPid] :: MxSupervisor -> SupervisorPid [childPid] :: MxSupervisor -> ChildPid [exitReason] :: MxSupervisor -> ExitReason -- | A child failed during init SupervisedChildInitFailed :: SupervisorPid -> ChildPid -> ChildInitFailure -> MxSupervisor [supervisorPid] :: MxSupervisor -> SupervisorPid [childPid] :: MxSupervisor -> ChildPid [initFailure] :: MxSupervisor -> ChildInitFailure -- | A child has been stopped SupervisedChildStopped :: SupervisorPid -> ChildRef -> DiedReason -> MxSupervisor [supervisorPid] :: MxSupervisor -> SupervisorPid [childRef] :: MxSupervisor -> ChildRef [diedReason] :: MxSupervisor -> DiedReason -- | A supervisor is shutting down SupervisorShutdown :: SupervisorPid -> ShutdownMode -> ExitReason -> MxSupervisor [supervisorPid] :: MxSupervisor -> SupervisorPid [shutdownMode] :: MxSupervisor -> ShutdownMode [exitRason] :: MxSupervisor -> ExitReason instance GHC.Generics.Generic Control.Distributed.Process.Supervisor.Management.Register instance GHC.Generics.Generic Control.Distributed.Process.Supervisor.Management.UnRegister instance GHC.Show.Show Control.Distributed.Process.Supervisor.Management.SupMxChan instance GHC.Generics.Generic Control.Distributed.Process.Supervisor.Management.SupMxChan instance Data.Binary.Class.Binary Control.Distributed.Process.Supervisor.Management.SupMxChan instance Control.DeepSeq.NFData Control.Distributed.Process.Supervisor.Management.SupMxChan instance Data.Hashable.Class.Hashable Control.Distributed.Process.Supervisor.Management.SupMxChan instance GHC.Classes.Eq Control.Distributed.Process.Supervisor.Management.SupMxChan instance Data.Binary.Class.Binary Control.Distributed.Process.Supervisor.Management.UnRegister instance Control.DeepSeq.NFData Control.Distributed.Process.Supervisor.Management.UnRegister instance Data.Binary.Class.Binary Control.Distributed.Process.Supervisor.Management.Register instance Control.DeepSeq.NFData Control.Distributed.Process.Supervisor.Management.Register -- | 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 client functions in this module will -- cause the calling process to exit unless the specified supervisor -- process can be resolved. -- --
-- 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] ---- --
-- 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 ---- --
-- start = spawnLocal . run --start :: RestartStrategy -> ShutdownMode -> [ChildSpec] -> Process SupervisorPid -- | Run the supplied children using the provided restart strategy. run :: RestartStrategy -> ShutdownMode -> [ChildSpec] -> Process () -- | The maximum number of restarts a supervisor will tollerate, created by -- evaluating "maxRestarts". data MaxRestarts -- | Smart constructor for MaxRestarts. The maximum restart count -- must be a positive integer, otherwise you will see error "MaxR -- must be >= 0". maxRestarts :: Int -> MaxRestarts -- | A compulsary limit on the number of restarts that a supervisor will -- tolerate before it stops all child processes and then itself. If > -- MaxRestarts occur within the specified TimeInterval, -- the child will be stopped. This prevents the supervisor from entering -- an infinite loop of child process stops and restarts. data RestartLimit RestartLimit :: !MaxRestarts -> !TimeInterval -> RestartLimit [maxR] :: RestartLimit -> !MaxRestarts [maxT] :: RestartLimit -> !TimeInterval -- | Smart constructor for RestartLimit. limit :: MaxRestarts -> TimeInterval -> RestartLimit -- | Default RestartLimit of MaxR 1 within Seconds -- 1. defaultLimits :: RestartLimit -- | Instructs a supervisor on how to restart its children. 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 -- | Specifies the order in which a supervisor should apply restarts. 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 in insertion order in the child specs. These -- latter modes allow one to control the order in which siblings are -- restarted, and to exclude some siblings from restarting, 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 -- | Instructs a supervisor on how to instruct its children to stop running -- when the supervisor itself is shutting down. 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 -- | The result of an addChild request. data AddChildResult -- | The child was added correctly ChildAdded :: !ChildRef -> AddChildResult -- | The child failed to start ChildFailedToStart :: !StartFailure -> AddChildResult -- | The result of a startChild request. data StartChildResult -- | The child started successfully ChildStartOk :: !ChildRef -> StartChildResult -- | The child failed to start ChildStartFailed :: !StartFailure -> StartChildResult -- | The child key was not recognised by the supervisor ChildStartUnknownId :: 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 -- | Stop a running child. stopChild :: Addressable a => a -> ChildKey -> Process StopChildResult -- | The result of a stopChild request. data StopChildResult -- | The child was stopped successfully StopChildOk :: StopChildResult -- | The child key was not recognised by the supervisor StopChildUnknownId :: StopChildResult -- | Delete a supervised child. The child must already be stopped (see -- stopChild). 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 -- | The result of a restartChild request. data RestartChildResult -- | The child restarted successfully ChildRestartOk :: !ChildRef -> RestartChildResult -- | The child failed to restart ChildRestartFailed :: !StartFailure -> RestartChildResult -- | The child key was not recognised by the supervisor ChildRestartUnknownId :: RestartChildResult -- | Gracefully stop/shutdown 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] -- | Statistics about a running supervisor 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 -- | The RestartLimit for a given RestartStrategy getRestartIntensity :: RestartStrategy -> RestartLimit -- | How many child specs are defined for this supervisor definedChildren :: SupervisorStats -> Int -- | How many child specs define a worker (non-supervisor) definedWorkers :: SupervisorStats -> Int -- | How many child specs define a supervisor? definedSupervisors :: SupervisorStats -> Int -- | How many running child processes. runningChildren :: SupervisorStats -> Int -- | How many worker (non-supervisor) child processes are running. runningWorkers :: SupervisorStats -> Int -- | How many supervisor child processes are running runningSupervisors :: SupervisorStats -> Int -- | 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 -- | A child process failure during init will be reported using this datum data ChildInitFailure -- | The init failed with the corresponding message ChildInitFailure :: !String -> ChildInitFailure -- | The child told the supervisor to ignore its startup procedure ChildInitIgnore :: ChildInitFailure instance GHC.Generics.Generic Control.Distributed.Process.Supervisor.DeleteChild instance GHC.Generics.Generic Control.Distributed.Process.Supervisor.FindReq instance GHC.Generics.Generic Control.Distributed.Process.Supervisor.StatsReq instance GHC.Generics.Generic Control.Distributed.Process.Supervisor.ListReq 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.StartChildReq 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.Classes.Eq Control.Distributed.Process.Supervisor.DelayedRestart instance GHC.Show.Show Control.Distributed.Process.Supervisor.DelayedRestart instance GHC.Generics.Generic Control.Distributed.Process.Supervisor.DelayedRestart instance GHC.Classes.Eq Control.Distributed.Process.Supervisor.StopChildReq instance GHC.Show.Show Control.Distributed.Process.Supervisor.StopChildReq instance GHC.Generics.Generic Control.Distributed.Process.Supervisor.StopChildReq instance GHC.Generics.Generic Control.Distributed.Process.Supervisor.IgnoreChildReq instance Control.Distributed.Process.Extras.SystemLog.Logger Control.Distributed.Process.Supervisor.LogSink instance Data.Binary.Class.Binary Control.Distributed.Process.Supervisor.IgnoreChildReq instance Control.DeepSeq.NFData Control.Distributed.Process.Supervisor.IgnoreChildReq instance Data.Binary.Class.Binary Control.Distributed.Process.Supervisor.StopChildReq instance Control.DeepSeq.NFData Control.Distributed.Process.Supervisor.StopChildReq instance Data.Binary.Class.Binary Control.Distributed.Process.Supervisor.DelayedRestart instance Control.DeepSeq.NFData Control.Distributed.Process.Supervisor.DelayedRestart 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.StartChildReq instance Control.DeepSeq.NFData Control.Distributed.Process.Supervisor.StartChildReq 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.ListReq instance Control.DeepSeq.NFData Control.Distributed.Process.Supervisor.ListReq 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.FindReq instance Control.DeepSeq.NFData Control.Distributed.Process.Supervisor.FindReq instance Data.Binary.Class.Binary Control.Distributed.Process.Supervisor.DeleteChild instance Control.DeepSeq.NFData 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.Static.Static (Control.Distributed.Process.Internal.Types.Process ()))