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.
- data CallbackType
- type WorkerAction = IO ()
- data WorkerError = WorkerCallbackFailed {
- workerId :: !WorkerId
- workerActionError :: !(Maybe SomeException)
- callbackType :: !CallbackType
- workerCallbackError :: !SomeException
- data WorkerOptions = WorkerOptions {
- workerName :: !WorkerName
- workerOnFailure :: !(SomeException -> IO ())
- workerOnCompletion :: !(IO ())
- workerOnTermination :: !(IO ())
- workerTerminationPolicy :: !WorkerTerminationPolicy
- workerRestartStrategy :: !WorkerRestartStrategy
- data WorkerRestartStrategy
- data WorkerSpec = WorkerSpec {
- workerAction :: WorkerAction
- workerName :: !WorkerName
- workerOnFailure :: !(SomeException -> IO ())
- workerOnCompletion :: !(IO ())
- workerOnTermination :: !(IO ())
- workerTerminationPolicy :: !WorkerTerminationPolicy
- workerRestartStrategy :: !WorkerRestartStrategy
- data WorkerTerminationOrder
- data WorkerTerminationPolicy
- data Capataz = Capataz {
- capatazRuntime :: !CapatazRuntime
- capatazEnv :: !CapatazEnv
- capatazAsync :: !(Async ())
- capatazTeardown :: !Teardown
- data CapatazEvent
- = InvalidCapatazStatusReached {
- capatazId :: !CapatazId
- capatazName :: !CapatazName
- eventTime :: !UTCTime
- | CapatazStatusChanged {
- capatazId :: !CapatazId
- capatazName :: !CapatazName
- prevCapatazStatus :: !CapatazStatus
- newCapatazStatus :: !CapatazStatus
- eventTime :: !UTCTime
- | WorkerTerminated {
- capatazName :: !CapatazName
- capatazId :: !CapatazId
- workerThreadId :: !WorkerThreadId
- workerId :: !WorkerId
- workerName :: !WorkerName
- terminationReason :: !Text
- eventTime :: !UTCTime
- | WorkerStarted {
- capatazName :: !CapatazName
- capatazId :: !CapatazId
- workerThreadId :: !WorkerThreadId
- workerId :: !WorkerId
- workerName :: !WorkerName
- eventTime :: !UTCTime
- | WorkerRestarted {
- capatazName :: !CapatazName
- capatazId :: !CapatazId
- workerThreadId :: !WorkerThreadId
- workerId :: !WorkerId
- workerName :: !WorkerName
- workerRestartCount :: !Int
- eventTime :: !UTCTime
- | WorkerCompleted {
- capatazName :: !CapatazName
- capatazId :: !CapatazId
- workerThreadId :: !WorkerThreadId
- workerId :: !WorkerId
- workerName :: !WorkerName
- eventTime :: !UTCTime
- | WorkerFailed {
- capatazName :: !CapatazName
- capatazId :: !CapatazId
- workerThreadId :: !WorkerThreadId
- workerId :: !WorkerId
- workerName :: !WorkerName
- workerError :: !SomeException
- eventTime :: !UTCTime
- | WorkerCallbackExecuted {
- capatazName :: !CapatazName
- capatazId :: !CapatazId
- workerThreadId :: !WorkerThreadId
- workerId :: !WorkerId
- workerName :: !WorkerName
- workerCallbackError :: !(Maybe SomeException)
- callbackType :: !CallbackType
- eventTime :: !UTCTime
- | WorkersTerminationStarted {
- capatazName :: !CapatazName
- capatazId :: !CapatazId
- terminationReason :: !Text
- eventTime :: !UTCTime
- | WorkersTerminationFinished {
- capatazName :: !CapatazName
- capatazId :: !CapatazId
- terminationReason :: !Text
- eventTime :: !UTCTime
- | CapatazFailed {
- capatazName :: !CapatazName
- capatazId :: !CapatazId
- capatazError :: !SomeException
- eventTime :: !UTCTime
- | CapatazTerminated {
- capatazName :: !CapatazName
- capatazId :: !CapatazId
- eventTime :: !UTCTime
- | CapatazShutdownInvoked {
- capatazName :: !CapatazName
- capatazId :: !CapatazId
- eventTime :: !UTCTime
- = InvalidCapatazStatusReached {
- data CapatazOptions = CapatazOptions {
- capatazName :: Text
- capatazIntensity :: !Int
- capatazPeriodSeconds :: !NominalDiffTime
- capatazRestartStrategy :: !CapatazRestartStrategy
- capatazWorkerSpecList :: ![WorkerSpec]
- capatazWorkerTerminationOrder :: !WorkerTerminationOrder
- onCapatazIntensityReached :: !(IO ())
- notifyEvent :: !(CapatazEvent -> IO ())
- data CapatazRestartStrategy
- data CapatazStatus
- = Initializing
- | Running
- | Halting
- | Halted
- defWorkerOptions :: WorkerOptions
- defWorkerSpec :: WorkerSpec
- defCapatazOptions :: CapatazOptions
- forkWorker :: WorkerOptions -> IO () -> Capataz -> IO WorkerId
- forkCapataz :: CapatazOptions -> IO Capataz
- terminateWorker :: Text -> WorkerId -> Capataz -> IO ()
- capatazToAsync :: Capataz -> Async ()
- teardown :: ITeardown teardown => teardown -> IO TeardownResult
Types
data CallbackType Source #
Internal record that indicates what type of callback function is being invoked; this is used for telemetry purposes
type WorkerAction = IO () Source #
data WorkerError Source #
Internal exception triggered when a callback of a Worker fails
WorkerCallbackFailed | |
|
data WorkerOptions Source #
Utility record used to specify options to a Worker instance
WorkerOptions | |
|
data WorkerRestartStrategy Source #
data WorkerSpec Source #
WorkerSpec is a representation of the WorkerOptions record that embeds
the IO ()
sub-routine of the worker thread. This record is used when we
want to bound worker threads to a Capataz instance
WorkerSpec | |
|
Generic WorkerSpec Source # | |
type Rep WorkerSpec Source # | |
data WorkerTerminationOrder Source #
Specifies how order in which workers should be terminated by a Capataz in case of restart or shutdown; default is OldestFirst
NewestFirst | Terminate worker threads from most recent to oldest |
OldestFirst | Terminate worker threads from oldest to most recent |
data WorkerTerminationPolicy Source #
Defines how a Worker termination should be handled, default WorkerTerminationPolicy is 3 seconds
Infinity | Waits until infinity for the worker to terminate |
BrutalTermination | Worker is terminated wihtout a chance to call its callback |
TimeoutMillis !Int | Allows n milliseconds for worker termination callback to be executed, otherwise "BrutalTermination occurs" |
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.
Capataz | |
|
data CapatazEvent Source #
Event passed to the "notifyEvent" callback sub-routine, this events can be used to monitor the capataz system and understanding what is doing. This provides high levels of telemetry for the Capataz instance, so is mainly used for logging, monitoring and testing purposes.
data CapatazOptions Source #
Utility record used to specify options to a Capataz instance
CapatazOptions | |
|
data CapatazRestartStrategy Source #
Specifies how a Capataz should restart a failing worker. Default is OneForOne
data CapatazStatus Source #
Internal state machine record that indicates the state of a Capataz
Initializing | This state is set when Worker is created and it spawn static worker threads |
Running | This state is set when the Capataz thread is listenting to both ControlAction and MonitorEvent messages |
Halting | This state is set when the Capataz thread is terminating it's assigned worker |
Halted | The Capataz thread is done |
defWorkerOptions :: WorkerOptions Source #
Default options to easily create worker instances: * name defaults to "default-worker" * has a Transient worker restart strategy * has a termination policy of three (3) seconds
defWorkerSpec :: WorkerSpec Source #
Default spec to easily create worker instances:
* IO ()
sub-routine simply returns unit
* name defaults to "default-worker"
* has a Transient worker restart strategy
* has a termination policy of three (3) seconds
defCapatazOptions :: CapatazOptions Source #
Default options to easily create capataz instances: * name defaults to "default-capataz" * intensity error tolerance is set to 1 error every 5 seconds * has a "OneForOne " capataz restart strategy * has a termination order of OldestFirst
Core functionality
:: WorkerOptions | Worker options (restart, name, callbacks, etc) |
-> IO () | IO sub-routine that will be executed on worker thread |
-> Capataz | Capataz instance that supervises the worker |
-> IO WorkerId | An identifier that can be used to terminate the Worker |
Creates a worker green thread "IO ()" sub-routine, and depending in options defined in the WorkerOptions record, it will restart the Worker sub-routine in case of failures
forkCapataz :: CapatazOptions -> IO Capataz Source #
Creates a Capataz record, which represents a supervision thread which monitors failure on worker threads defined in the CapatazOptions or worker threads that are created dynamically using "forkWorker".
terminateWorker :: Text -> WorkerId -> Capataz -> IO () Source #
Stops the execution of a worker green thread being supervised by the given Capataz instance, if the WorkerId does not belong to the Capataz, the operation does not perform any side-effect.
Note: If your worker has a Permanent worker restart strategy, the worker thread will be restarted again; so use a Transient restart strategy instead.
Utility functions
capatazToAsync :: Capataz -> Async () Source #
Teardown (re-exported)
teardown :: ITeardown teardown => teardown -> IO TeardownResult #
Executes teardown sub-routine returning a TeardownResult