| Safe Haskell | None |
|---|---|
| Language | Haskell2010 |
Control.Concurrent.Capataz
Contents
Description
Public API for the capataz library
Capataz is a library that brings an OTP-like supervisor API to the Haskell concurrency toolset.
- class HasSupervisor a where
- data CallbackType
- type WorkerId = UUID
- data WorkerRestartStrategy
- data WorkerTerminationPolicy
- data WorkerOptions
- type ProcessId = UUID
- data ProcessSpec
- data ProcessType
- data ProcessTerminationOrder
- data ProcessError = ProcessCallbackFailed {}
- type SupervisorId = UUID
- data Supervisor
- data SupervisorRestartStrategy
- data SupervisorStatus
- = Initializing
- | Running
- | Halting
- | Halted
- data SupervisorOptions
- data CapatazOptions
- data Capataz
- buildSupervisorOptions :: SupervisorName -> (SupervisorOptions -> SupervisorOptions) -> SupervisorOptions
- buildSupervisorOptionsWithDefaults :: SupervisorName -> SupervisorOptions
- buildWorkerOptions :: WorkerName -> IO () -> (WorkerOptions -> WorkerOptions) -> WorkerOptions
- buildWorkerOptionsWithDefaults :: WorkerName -> IO () -> WorkerOptions
- supervisorSpec :: SupervisorName -> (SupervisorOptions -> SupervisorOptions) -> ProcessSpec
- supervisorSpecWithDefaults :: SupervisorName -> ProcessSpec
- workerSpec :: WorkerName -> IO () -> (WorkerOptions -> WorkerOptions) -> ProcessSpec
- workerSpecWithDefaults :: WorkerName -> IO () -> ProcessSpec
- onSystemEventL :: Functor f => ((CapatazEvent -> IO ()) -> f (CapatazEvent -> IO ())) -> CapatazOptions -> f CapatazOptions
- supervisorIntensityL :: (HasSupervisorIntensity s, Functor f) => (Int -> f Int) -> s -> f s
- supervisorPeriodSecondsL :: (HasSupervisorPeriodSeconds s, Functor f) => (NominalDiffTime -> f NominalDiffTime) -> s -> f s
- supervisorRestartStrategyL :: (HasSupervisorRestartStrategy s, Functor f) => (SupervisorRestartStrategy -> f SupervisorRestartStrategy) -> s -> f s
- supervisorProcessSpecListL :: (HasSupervisorProcessSpecList s, Functor f) => ([ProcessSpec] -> f [ProcessSpec]) -> s -> f s
- supervisorProcessTerminationOrderL :: (HasSupervisorProcessTerminationOrder s, Functor f) => (ProcessTerminationOrder -> f ProcessTerminationOrder) -> s -> f s
- supervisorOnIntensityReachedL :: (HasSupervisorIntensityReachedCallback s, Functor f) => (IO () -> f (IO ())) -> s -> f s
- supervisorOnFailureL :: (HasSupervisorFailureCallback s, Functor f) => ((SomeException -> IO ()) -> f (SomeException -> IO ())) -> s -> f s
- workerOnFailureL :: Functor f => ((SomeException -> IO ()) -> f (SomeException -> IO ())) -> WorkerOptions -> f WorkerOptions
- workerOnCompletionL :: Functor f => (IO () -> f (IO ())) -> WorkerOptions -> f WorkerOptions
- workerOnTerminationL :: Functor f => (IO () -> f (IO ())) -> WorkerOptions -> f WorkerOptions
- workerTerminationPolicyL :: Functor f => (WorkerTerminationPolicy -> f WorkerTerminationPolicy) -> WorkerOptions -> f WorkerOptions
- workerRestartStrategyL :: Functor f => (WorkerRestartStrategy -> f WorkerRestartStrategy) -> WorkerOptions -> f WorkerOptions
- forkWorker :: HasSupervisor supervisor => WorkerOptions -> supervisor -> IO WorkerId
- forkSupervisor :: HasSupervisor parentSupervisor => SupervisorOptions -> parentSupervisor -> IO Supervisor
- forkCapataz :: Text -> (CapatazOptions -> CapatazOptions) -> IO Capataz
- terminateProcess :: HasSupervisor supervisor => Text -> ProcessId -> supervisor -> IO Bool
- joinCapatazThread :: Capataz -> IO ()
- getSupervisorProcessId :: Supervisor -> ProcessId
- getSupervisorAsync :: Supervisor -> Async ()
- getCapatazTeardown :: Capataz -> Teardown
- teardown :: ITeardown teardown => teardown -> IO TeardownResult
- (.~) :: ASetter s t a b -> b -> s -> t
- (&) :: a -> (a -> b) -> b
- set :: ASetter s t a b -> b -> s -> t
Types
class HasSupervisor a where Source #
Utility typeclass to call public supervision API with types that contain a supervisor (e.g. Capataz record).
Minimal complete definition
Instances
data CallbackType Source #
Internal record that indicates what type of callback function is being invoked; this is used for telemetry purposes
Constructors
| OnCompletion | |
| OnFailure | |
| OnTermination |
Instances
data WorkerRestartStrategy Source #
Specifies how a Supervisor deals with the lifecycle of worker process in case of completion without errors and failure.
data WorkerTerminationPolicy Source #
Defines how a Worker process termination should be handled by its supervisor.
Constructors
| Infinity | Supervisor waits until infinity for the worker termination callback to finish execution. |
| BrutalTermination | Supervisor terminates worker process without a chance to call its termination callback. |
| TimeoutMillis !Int | Supervisor allows a number of milliseconds for worker termination callback complete, if not completed by specified milliseconds the termination is cancelled via a BrutalTermination signal. |
data WorkerOptions Source #
Specifies all options that can be used to create a Worker Process. You may create a record of this type via the smart constructor "buildWorkerOptions".
Instances
data ProcessSpec Source #
Record used to specify how to build a runtime Process in a static supervision tree; to create values of this type, you must use:
- "workerSpec" or "workerSpecWithDefaults" to build a worker process
- "supervisorSpec" or "supervisorSpecWithDefaults" to build a supervisor process
Constructors
| WorkerSpec WorkerOptions | |
| SupervisorSpec SupervisorOptions |
data ProcessTerminationOrder Source #
Specifies the order in which supervised process should be terminated by a Supervisor in case of a restart or shutdown.
Constructors
| NewestFirst | Supervisor terminates supervised process from most recent to oldest. |
| OldestFirst | Supervisor terminates supervised process from oldest to most recent. |
data ProcessError Source #
Internal exception triggered when a callback of a Worker fails
Constructors
| ProcessCallbackFailed | |
Fields | |
Instances
type SupervisorId = UUID Source #
data Supervisor Source #
Instances
data SupervisorRestartStrategy Source #
Specifies how a Supervisor restarts a failing process.
data SupervisorStatus Source #
Internal record used as a state machine, indicating the state of a supervisor process
Constructors
| Initializing | This state is set when the process is created and it starts spawning its static process list. |
| Running | This state is set when the supervisor process starts listenting to both ControlAction and MonitorEvent messages. |
| Halting | This state is set when the supervisor process is terminating it's assigned worker |
| Halted | This state is set when the supervisor process is finished |
data SupervisorOptions Source #
Instances
data CapatazOptions Source #
Allows to:
- Specify options for The root supervisor of a capataz system.
- Provie a "notifyEvent" callback to monitor or log a capataz system.
Instances
Record that contains the environment of a capataz monitor, this is used as the main record to create workers and to stop the supervisor thread.
Default Options for Capataz Processes
buildSupervisorOptions Source #
Arguments
| :: SupervisorName | Name used for telemetry purposes |
| -> (SupervisorOptions -> SupervisorOptions) | Function to modify default supervisor options |
| -> SupervisorOptions |
Builds a SupervisorOptions record with defaults from "buildSupervisorOptionsWithDefaults". This function allows overrides of these defaults using lenses.
This function is intended to be used in combination with "forkSupervisor".
buildSupervisorOptionsWithDefaults Source #
Arguments
| :: SupervisorName | Name used for telemetry purposes |
| -> SupervisorOptions |
Builds a SupervisorOptions record with defaults to create a supervisor process, these defaults are:
- Intensity error tolerance is set to 1 error every 5 seconds
- A SupervisorRestartStrategy of OneForOne
- A ProcessTerminationOrder of OldestFirst
This function is intended to be used in combination with "forkSupervisor".
Arguments
| :: WorkerName | Name used for telemetry purposes |
| -> IO () | IO sub-routine to be supervised |
| -> (WorkerOptions -> WorkerOptions) | Function to modify default worker options |
| -> WorkerOptions |
Builds a WorkerOptions record, keeps the defaults from "buildWorkerOptionsWithDefaults" but allows overrides using lenses.
This function is intended to be used in combination with "forkWorker". See the ... example in the examples directory for a demonstration.
buildWorkerOptionsWithDefaults Source #
Arguments
| :: WorkerName | Name used for telemetry purposes |
| -> IO () | IO sub-routine to be supervised |
| -> WorkerOptions |
Builds a WorkerOptions record with defaults to create a worker process, the defaults are:
- A Transient WorkerRestartStrategy
- A WorkerTerminationPolicy of a 3 seconds timeout
- A _completion_ callback that just returns unit
- A _termination_ callback that just returns unit
- A _failure_ callback that just returns unit
This function is intended to be used in combination with "forkWorker", for creating a worker in an static supervision tree, use "workerSpecWithDefaults" instead. See the ... example for a demonstration.
Arguments
| :: SupervisorName | Name used for telemetry purposes |
| -> (SupervisorOptions -> SupervisorOptions) | Function to modify default supervisor options |
| -> ProcessSpec |
Builds a ProcessSpec record for a supervisor process with defaults from "supervisorSpecWithDefaults". This function allows overrides of these defaults using lenses.
This function is used when building a supervisor branch in a static supervision trees.
supervisorSpecWithDefaults Source #
Arguments
| :: SupervisorName | Name used for telemetry purposes |
| -> ProcessSpec |
Builds a ProcessSpec record for a supervisor process with defaults from "buildSupervisorOptionsWithDefaults".
This function is used when building a supervisor branch in a static supervision trees.
Arguments
| :: WorkerName | Name used for telemetry purposes |
| -> IO () | IO sub-routine to be supervised |
| -> (WorkerOptions -> WorkerOptions) | Function to modify default worker options |
| -> ProcessSpec |
Builds a ProcessSpec record for a worker process with defaults from "workerSpecWithDefaults". This function allows overrides of these defaults using lenses.
This function is used when building a worker in a static supervision tree.
workerSpecWithDefaults Source #
Arguments
| :: WorkerName | Name used for telemetry purposes |
| -> IO () | IO sub-routine to be supervised |
| -> ProcessSpec |
Builds a ProcessSpec record for a worker process with defaults from "buildSupervisorOptionsWithDefaults".
This function is used when building a worker in a static supervision tree.
Lenses to modify Option Records
onSystemEventL :: Functor f => ((CapatazEvent -> IO ()) -> f (CapatazEvent -> IO ())) -> CapatazOptions -> f CapatazOptions Source #
supervisorIntensityL :: (HasSupervisorIntensity s, Functor f) => (Int -> f Int) -> s -> f s Source #
Specifies how many errors is a supervisor able to handle; check: http://erlang.org/doc/design_principles/sup_princ.html#max_intensity.
supervisorPeriodSecondsL :: (HasSupervisorPeriodSeconds s, Functor f) => (NominalDiffTime -> f NominalDiffTime) -> s -> f s Source #
Specifies period of time in which a supervisor can receive a number of errors specified in "supervisorIntensityL".
supervisorRestartStrategyL :: (HasSupervisorRestartStrategy s, Functor f) => (SupervisorRestartStrategy -> f SupervisorRestartStrategy) -> s -> f s Source #
Specifies the SupervisorRestartStrategy for a root supervisor.
supervisorProcessSpecListL :: (HasSupervisorProcessSpecList s, Functor f) => ([ProcessSpec] -> f [ProcessSpec]) -> s -> f s Source #
Specifies a static list of processes that start automatically with a supervisor.
supervisorProcessTerminationOrderL :: (HasSupervisorProcessTerminationOrder s, Functor f) => (ProcessTerminationOrder -> f ProcessTerminationOrder) -> s -> f s Source #
Specifies order in which a supervisor is going to terminate its supervised processes.
supervisorOnIntensityReachedL :: (HasSupervisorIntensityReachedCallback s, Functor f) => (IO () -> f (IO ())) -> s -> f s Source #
Specifies a callback sub-routine that gets executed when there is a breach in a supervisor's error intensity.
supervisorOnFailureL :: (HasSupervisorFailureCallback s, Functor f) => ((SomeException -> IO ()) -> f (SomeException -> IO ())) -> s -> f s Source #
Specifies callback sub-routine that gets executed when a supervisor fails.
workerOnFailureL :: Functor f => ((SomeException -> IO ()) -> f (SomeException -> IO ())) -> WorkerOptions -> f WorkerOptions Source #
Specifies callback that gets executed when worker sub-routine has runtime error.
NOTE: the given sub-routine execution may be interrupted depending on the worker WorkerTerminationPolicy.
workerOnCompletionL :: Functor f => (IO () -> f (IO ())) -> WorkerOptions -> f WorkerOptions Source #
Specifies callback that gets executed when worker sub-routine completes with no errors.
NOTE: the given sub-routine execution may be interrupted depending on the worker WorkerTerminationPolicy.
workerOnTerminationL :: Functor f => (IO () -> f (IO ())) -> WorkerOptions -> f WorkerOptions Source #
Specifies callback that gets executed when worker sub-routine is terminated by its supervisor; this may happen in case of a capataz system shutdown or when there is an AllForOne restart policy in place.
NOTE: the given sub-routine execution may be interrupted depending on the worker WorkerTerminationPolicy.
workerTerminationPolicyL :: Functor f => (WorkerTerminationPolicy -> f WorkerTerminationPolicy) -> WorkerOptions -> f WorkerOptions Source #
Specifies how to handle a worker termination. See WorkerTerminationPolicy documentation for more details.
workerRestartStrategyL :: Functor f => (WorkerRestartStrategy -> f WorkerRestartStrategy) -> WorkerOptions -> f WorkerOptions Source #
Specifies how supervisor should deal with an error when worker fails or completes. See WorkerRestartStrategy documentation for more details.
Core functionality
Arguments
| :: HasSupervisor supervisor | |
| => WorkerOptions | Worker options (restart, name, callbacks, etc) |
| -> supervisor | Supervisor that supervises the worker |
| -> IO WorkerId | An identifier that can be used to terminate the Worker |
Creates a green thread from an "IO ()" sub-routine. Depending in options defined in the WorkerOptions record, it will automatically restart this sub-routine in case of failures.
See documentation of related functions:
- "buildWorkerOptionsWithDefault"
- "buildWorkerOptions"
Arguments
| :: HasSupervisor parentSupervisor | |
| => SupervisorOptions | Supervisor options |
| -> parentSupervisor | Parent supervisor instance that supervises new supervisor |
| -> IO Supervisor | A record used to dynamically create and supervise other processes |
Creates a green thread which monitors other green threads for failures and restarts them using settings defined on SupervisorOptions.
See documentation of related functions:
- "buildSupervisorOptionsWithDefault"
- "buildSupervisorOptions"
forkCapataz :: Text -> (CapatazOptions -> CapatazOptions) -> IO Capataz Source #
Creates a Capataz record, which holds both a root supervisor and a Teardown to shut down the system. The root supervisor monitors failures on process threads defined with "supervisorProcessSpecList" or created dynamically using "forkWorker" or "forkSupervisor".
terminateProcess :: HasSupervisor supervisor => Text -> ProcessId -> supervisor -> IO Bool Source #
Utility functions
joinCapatazThread :: Capataz -> IO () Source #
Joins the thread of the root supervisor of the given capataz system to the current thread.
getSupervisorProcessId :: Supervisor -> ProcessId Source #
Gets the process identifier of a Supervisor; normally used for termination.
getSupervisorAsync :: Supervisor -> Async () Source #
Teardown (re-exported)
teardown :: ITeardown teardown => teardown -> IO TeardownResult #
Executes teardown sub-routine returning a TeardownResult