Safe Haskell | None |
---|---|
Language | Haskell2010 |
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
- type WorkerName = Text
- data WorkerRestartStrategy
- data WorkerTerminationPolicy
- data WorkerOptions m
- type ProcessId = UUID
- data ProcessSpec m
- = WorkerSpec (WorkerOptions m)
- | SupervisorSpec (SupervisorOptions m)
- data ProcessType
- data ProcessTerminationOrder
- data ProcessError = ProcessCallbackFailed {}
- type SupervisorId = UUID
- type SupervisorName = Text
- data Supervisor m
- data SupervisorRestartStrategy
- data SupervisorStatus
- = Initializing
- | Running
- | Halting
- | Halted
- data SupervisorOptions m
- data CapatazOptions m
- data Capataz m
- buildSupervisorOptions :: Monad m => SupervisorName -> (SupervisorOptions m -> SupervisorOptions m) -> SupervisorOptions m
- buildSupervisorOptionsWithDefaults :: Monad m => SupervisorName -> SupervisorOptions m
- buildWorkerOptions :: Monad m => WorkerName -> m () -> (WorkerOptions m -> WorkerOptions m) -> WorkerOptions m
- buildWorkerOptionsWithDefaults :: Monad m => WorkerName -> m () -> WorkerOptions m
- supervisorSpec :: Monad m => SupervisorName -> (SupervisorOptions m -> SupervisorOptions m) -> ProcessSpec m
- supervisorSpecWithDefaults :: Monad m => SupervisorName -> ProcessSpec m
- workerSpec :: Monad m => WorkerName -> m () -> (WorkerOptions m -> WorkerOptions m) -> ProcessSpec m
- workerSpecWithDefaults :: Monad m => WorkerName -> m () -> ProcessSpec m
- onSystemEventL :: Functor f => ((CapatazEvent -> m ()) -> f (CapatazEvent -> m ())) -> CapatazOptions m -> f (CapatazOptions m)
- 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 m] -> f [ProcessSpec m]) -> s m -> f (s m)
- supervisorProcessTerminationOrderL :: (HasSupervisorProcessTerminationOrder s, Functor f) => (ProcessTerminationOrder -> f ProcessTerminationOrder) -> s -> f s
- supervisorOnIntensityReachedL :: (HasSupervisorIntensityReachedCallback s, Functor f) => (m () -> f (m ())) -> s m -> f (s m)
- supervisorOnFailureL :: (HasSupervisorFailureCallback s, Functor f) => ((SomeException -> m ()) -> f (SomeException -> m ())) -> s m -> f (s m)
- workerOnFailureL :: Functor f => ((SomeException -> m ()) -> f (SomeException -> m ())) -> WorkerOptions m -> f (WorkerOptions m)
- workerOnCompletionL :: Functor f => (m () -> f (m ())) -> WorkerOptions m -> f (WorkerOptions m)
- workerOnTerminationL :: Functor f => (m () -> f (m ())) -> WorkerOptions m -> f (WorkerOptions m)
- workerTerminationPolicyL :: Functor f => (WorkerTerminationPolicy -> f WorkerTerminationPolicy) -> WorkerOptions m -> f (WorkerOptions m)
- workerRestartStrategyL :: Functor f => (WorkerRestartStrategy -> f WorkerRestartStrategy) -> WorkerOptions m -> f (WorkerOptions m)
- forkWorker :: (MonadIO m, HasSupervisor supervisor) => WorkerOptions m -> supervisor m -> m WorkerId
- forkSupervisor :: (MonadIO m, HasSupervisor parentSupervisor) => SupervisorOptions m -> parentSupervisor m -> m (Supervisor m)
- forkCapataz :: (MonadUnliftIO m, MonadIO m) => Text -> (CapatazOptions m -> CapatazOptions m) -> m (Capataz m)
- terminateCapataz :: MonadIO m => Capataz m -> m TeardownResult
- terminateCapataz_ :: MonadIO m => Capataz m -> m ()
- terminateProcess :: (MonadIO m, HasSupervisor supervisor) => Text -> ProcessId -> supervisor m -> m Bool
- joinCapatazThread :: MonadIO m => Capataz m -> m ()
- getSupervisorProcessId :: Supervisor m -> ProcessId
- getSupervisorAsync :: Supervisor m -> Async ()
- getCapatazTeardown :: Capataz m -> Teardown
- data TeardownResult :: *
- (&) :: 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).
getSupervisor :: a m -> Supervisor m Source #
Fetches a supervisor from a record internals.
data CallbackType Source #
Internal record that indicates what type of callback function is being invoked; this is used for telemetry purposes
type WorkerName = Text Source #
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.
Since: 0.0.0.0
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 m 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
.
Since: 0.1.0.0
Generic (WorkerOptions m) Source # | |
type Rep (WorkerOptions m) Source # | |
data ProcessSpec m 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
orworkerSpecWithDefaults
to build a worker processsupervisorSpec
orsupervisorSpecWithDefaults
to build a supervisor process
Since: 0.1.0.0
data ProcessType Source #
data ProcessTerminationOrder Source #
Specifies the order in which supervised process should be terminated by a Supervisor in case of a restart or shutdown.
Since: 0.0.0.0
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
type SupervisorId = UUID Source #
type SupervisorName = Text Source #
data Supervisor m Source #
data SupervisorRestartStrategy Source #
Specifies how a Supervisor restarts a failing process.
Since: 0.0.0.0
data SupervisorStatus Source #
Internal record used as a state machine, indicating the state of a supervisor process
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 m Source #
data CapatazOptions m Source #
Allows to:
- Specify options for the root
Supervisor
of a capataz system. - Provide a
$sel:notifyEvent:ParentSupervisorEnv
callback to monitor or log a capataz system.
Since: 0.1.0.0
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.
Since: 0.0.0.0
Default Options for Capataz Processes
buildSupervisorOptions Source #
:: Monad m | |
=> SupervisorName | Name used for telemetry purposes |
-> (SupervisorOptions m -> SupervisorOptions m) | Function to modify default supervisor options |
-> SupervisorOptions m |
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
.
Since: 0.1.0.0
buildSupervisorOptionsWithDefaults Source #
:: Monad m | |
=> SupervisorName | Name used for telemetry purposes |
-> SupervisorOptions m |
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
ofOneForOne
- A
ProcessTerminationOrder
ofOldestFirst
This function is intended to be used in combination with forkSupervisor
.
Since: 0.1.0.0
:: Monad m | |
=> WorkerName | Name used for telemetry purposes |
-> m () | Process sub-routine to be supervised |
-> (WorkerOptions m -> WorkerOptions m) | Function to modify default worker options |
-> WorkerOptions m |
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
capataz-simple-example project in the examples directory for a demonstration.
Since: 0.1.0.0
buildWorkerOptionsWithDefaults Source #
:: Monad m | |
=> WorkerName | Name used for telemetry purposes |
-> m () |
|
-> WorkerOptions m |
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
capataz-simple-example project in the examples directory for a demonstration.
Since: 0.1.0.0
:: Monad m | |
=> SupervisorName | Name used for telemetry purposes |
-> (SupervisorOptions m -> SupervisorOptions m) |
|
-> ProcessSpec m |
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.
Since: 0.1.0.0
supervisorSpecWithDefaults Source #
:: Monad m | |
=> SupervisorName | Name used for telemetry purposes |
-> ProcessSpec m |
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.
Since: 0.1.0.0
:: Monad m | |
=> WorkerName | Name used for telemetry purposes |
-> m () |
|
-> (WorkerOptions m -> WorkerOptions m) | Function to modify default worker options |
-> ProcessSpec m |
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.
Since: 0.1.0.0
workerSpecWithDefaults Source #
:: Monad m | |
=> WorkerName | Name used for telemetry purposes |
-> m () | IO sub-routine to be supervised |
-> ProcessSpec m |
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.
Since: 0.1.0.0
Lenses to modify Option Records
onSystemEventL :: Functor f => ((CapatazEvent -> m ()) -> f (CapatazEvent -> m ())) -> CapatazOptions m -> f (CapatazOptions m) 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 m] -> f [ProcessSpec m]) -> s m -> f (s m) 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) => (m () -> f (m ())) -> s m -> f (s m) 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 -> m ()) -> f (SomeException -> m ())) -> s m -> f (s m) Source #
Specifies callback sub-routine that gets executed when a supervisor fails.
workerOnFailureL :: Functor f => ((SomeException -> m ()) -> f (SomeException -> m ())) -> WorkerOptions m -> f (WorkerOptions m) 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 => (m () -> f (m ())) -> WorkerOptions m -> f (WorkerOptions m) 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 => (m () -> f (m ())) -> WorkerOptions m -> f (WorkerOptions m) 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 m -> f (WorkerOptions m) Source #
Specifies how to handle a worker termination. See WorkerTerminationPolicy documentation for more details.
workerRestartStrategyL :: Functor f => (WorkerRestartStrategy -> f WorkerRestartStrategy) -> WorkerOptions m -> f (WorkerOptions m) Source #
Specifies how supervisor should deal with an error when worker fails or completes. See WorkerRestartStrategy documentation for more details.
Core functionality
:: (MonadIO m, HasSupervisor supervisor) | |
=> WorkerOptions m | Worker options (restart, name, callbacks, etc) |
-> supervisor m |
|
-> m WorkerId | An identifier that can be used to terminate the |
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:
:: (MonadIO m, HasSupervisor parentSupervisor) | |
=> SupervisorOptions m | Supervisor options |
-> parentSupervisor m | Parent supervisor instance that supervises new supervisor |
-> m (Supervisor m) | 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 :: (MonadUnliftIO m, MonadIO m) => Text -> (CapatazOptions m -> CapatazOptions m) -> m (Capataz m) 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 $sel:supervisorProcessSpecList:CapatazOptions
or created
dynamically using forkWorker
or forkSupervisor
.
terminateCapataz :: MonadIO m => Capataz m -> m TeardownResult Source #
Terminates a Capataz
system (all supervised threads) and returns a TeardownResult
Since: 0.2.0.0
terminateCapataz_ :: MonadIO m => Capataz m -> m () Source #
Terminates a Capataz
system (all supervised threads)
Since: 0.2.0.0
terminateProcess :: (MonadIO m, HasSupervisor supervisor) => Text -> ProcessId -> supervisor m -> m Bool Source #
Utility functions
joinCapatazThread :: MonadIO m => Capataz m -> m () Source #
Joins the thread of the root supervisor of the given capataz system to the current thread.
getSupervisorProcessId :: Supervisor m -> ProcessId Source #
Gets the process identifier of a Supervisor
; normally used for termination.
getSupervisorAsync :: Supervisor m -> Async () Source #
Teardown (re-exported)
data TeardownResult :: * #
Result from a Teardown
sub-routine