Involved Source Files Package failsafe provides fault tolerance and resilience patterns.
Failsafe-go adds fault tolerance to function execution. Functions can be wrapped with one or more resilience policies, for example:
result, err := failsafe.Get(fn, retryPolicy)
When multiple policies are provided, are composed around the fn and will handle its results in reverse order. For
example, consider:
failsafe.Get(fn, fallback, retryPolicy, circuitBreaker)
This creates the following composition when executing the fn and handling its result:
Fallback(RetryPolicy(CircuitBreaker(fn)))events.goexecution.goexecutor.gopolicy.goresult.go
Package-Level Type Names (total 12)
/* sort by: | */
Type Parameters:
S: any
R: any DelayablePolicyBuilder builds policies that can be delayed between executions. WithDelay configures the time to delay between execution attempts. WithDelayFunc configures a function that returns the time to delay before the next execution attempt.
Type Parameters:
R: any Execution contains information about an execution. AttemptStartTime returns the time that the most recent execution attempt started at. Attempts returns the number of execution attempts so far, including attempts that are currently in progress and
attempts that were blocked before being executed, such as by a CircuitBreaker or RateLimiter. These can include an initial
execution along with retries and hedges. Canceled returns a channel that is closed when the execution is canceled, either by an external Context or a
timeout.Timeout. Context returns the context configured for the execution, else context.Background if none was configured. For
executions involving a timeout or hedge, each attempt will get a separate child context. ElapsedAttemptTime returns the elapsed time since the last execution attempt began. ElapsedTime returns the elapsed time since initial execution attempt began. Executions returns the number of completed executions. Executions that are blocked, such as when a CircuitBreaker is
open, are not counted. Hedges returns the number of hedges that have been executed so far, including hedges that are currently in progress. IsCanceled returns whether the execution has been canceled by an external Context or a timeout.Timeout. IsFirstAttempt returns true when Attempts is 1, meaning this is the first execution attempt. IsHedge returns true when the execution is part of a hedged attempt. IsRetry returns true when Attempts is > 1, meaning the execution is being retried. LastError returns the error, if any, from the last execution attempt. LastResult returns the result, if any, from the last execution attempt. Retries returns the number of retries so far, including retries that are currently in progress. StartTime returns the time that the initial execution attempt started at.
Execution : ExecutionAttempt[R]
Execution : ExecutionInfo[R]
func github.com/failsafe-go/failsafe-go/policy.ExecutionInternal[R].CopyForCancellable() Execution[R]
func github.com/failsafe-go/failsafe-go/policy.ExecutionInternal[R].CopyForHedge() Execution[R]
func github.com/failsafe-go/failsafe-go/policy.ExecutionInternal[R].CopyWithResult(result *common.PolicyResult[R]) Execution[R]
Type Parameters:
R: any ExecutionAttempt contains information for an execution attempt. AttemptStartTime returns the time that the most recent execution attempt started at. Attempts returns the number of execution attempts so far, including attempts that are currently in progress and
attempts that were blocked before being executed, such as by a CircuitBreaker or RateLimiter. These can include an initial
execution along with retries and hedges. Context returns the context configured for the execution, else context.Background if none was configured. For
executions involving a timeout or hedge, each attempt will get a separate child context. ElapsedAttemptTime returns the elapsed time since the last execution attempt began. ElapsedTime returns the elapsed time since initial execution attempt began. Executions returns the number of completed executions. Executions that are blocked, such as when a CircuitBreaker is
open, are not counted. Hedges returns the number of hedges that have been executed so far, including hedges that are currently in progress. IsFirstAttempt returns true when Attempts is 1, meaning this is the first execution attempt. IsHedge returns true when the execution is part of a hedged attempt. IsRetry returns true when Attempts is > 1, meaning the execution is being retried. LastError returns the error, if any, from the last execution attempt. LastResult returns the result, if any, from the last execution attempt. Retries returns the number of retries so far, including retries that are currently in progress. StartTime returns the time that the initial execution attempt started at.
ExecutionAttempt : ExecutionInfo[R]
func github.com/failsafe-go/failsafe-go/policy.(*BaseDelayablePolicy)[R].ComputeDelay(exec ExecutionAttempt[R]) time.Duration
Type Parameters:
R: any ExecutionDoneEvent indicates an execution is done. The execution error, else nilExecutionInfoExecutionInfo The execution result, else the zero value for R Attempts returns the number of execution attempts so far, including attempts that are currently in progress and
attempts that were blocked before being executed, such as by a CircuitBreaker or RateLimiter. These can include an initial
execution along with retries and hedges. Context returns the context configured for the execution, else context.Background if none was configured. For
executions involving a timeout or hedge, each attempt will get a separate child context. ElapsedTime returns the elapsed time since initial execution attempt began. Executions returns the number of completed executions. Executions that are blocked, such as when a CircuitBreaker is
open, are not counted. Hedges returns the number of hedges that have been executed so far, including hedges that are currently in progress. Retries returns the number of retries so far, including retries that are currently in progress. StartTime returns the time that the initial execution attempt started at.
ExecutionDoneEvent : ExecutionInfo[R]
Type Parameters:
R: any ExecutionEvent indicates an execution was attempted.ExecutionAttemptExecutionAttempt[R] AttemptStartTime returns the time that the most recent execution attempt started at. Attempts returns the number of execution attempts so far, including attempts that are currently in progress and
attempts that were blocked before being executed, such as by a CircuitBreaker or RateLimiter. These can include an initial
execution along with retries and hedges. Context returns the context configured for the execution, else context.Background if none was configured. For
executions involving a timeout or hedge, each attempt will get a separate child context. ElapsedAttemptTime returns the elapsed time since the last execution attempt began. ElapsedTime returns the elapsed time since initial execution attempt began. Executions returns the number of completed executions. Executions that are blocked, such as when a CircuitBreaker is
open, are not counted. Hedges returns the number of hedges that have been executed so far, including hedges that are currently in progress. IsFirstAttempt returns true when Attempts is 1, meaning this is the first execution attempt. IsHedge returns true when the execution is part of a hedged attempt. IsRetry returns true when Attempts is > 1, meaning the execution is being retried. LastError returns the error, if any, from the last execution attempt. LastResult returns the result, if any, from the last execution attempt. Retries returns the number of retries so far, including retries that are currently in progress. StartTime returns the time that the initial execution attempt started at.
ExecutionEvent : ExecutionAttempt[R]
ExecutionEvent : ExecutionInfo[R]
ExecutionInfo contains execution info. Attempts returns the number of execution attempts so far, including attempts that are currently in progress and
attempts that were blocked before being executed, such as by a CircuitBreaker or RateLimiter. These can include an initial
execution along with retries and hedges. Context returns the context configured for the execution, else context.Background if none was configured. For
executions involving a timeout or hedge, each attempt will get a separate child context. ElapsedTime returns the elapsed time since initial execution attempt began. Executions returns the number of completed executions. Executions that are blocked, such as when a CircuitBreaker is
open, are not counted. Hedges returns the number of hedges that have been executed so far, including hedges that are currently in progress. Retries returns the number of retries so far, including retries that are currently in progress. StartTime returns the time that the initial execution attempt started at.Execution[...] (interface)ExecutionAttempt[...] (interface)ExecutionDoneEvent[...]ExecutionEvent[...]ExecutionScheduledEvent[...]
github.com/failsafe-go/failsafe-go/policy.ExecutionInternal[...] (interface)
Type Parameters:
R: any ExecutionResult provides the result of an asynchronous execution. Cancel cancels the execution if it is not already done, with ErrExecutionCanceled as the error. If a Context was
configured with the execution, a child context will be created for the execution and canceled as well. Done is a channel that is closed when the execution is done and the result can be retrieved via Get, Result, or Error. Error returns the execution error else nil, blocking until the execution is done. Get returns the execution result and error, else the default values, blocking until the execution is done. IsDone returns whether the execution is done and the result can be retrieved via Get. Result returns the execution result else its default value, blocking until the execution is done.
func GetAsync[R](fn func() (R, error), policies ...Policy[R]) ExecutionResult[R]
func GetWithExecutionAsync[R](fn func(exec Execution[R]) (R, error), policies ...Policy[R]) ExecutionResult[R]
func RunAsync(fn func() error, policies ...Policy[any]) ExecutionResult[any]
func RunWithExecutionAsync(fn func(exec Execution[any]) error, policies ...Policy[any]) ExecutionResult[any]
func Executor[R].GetAsync(fn func() (R, error)) ExecutionResult[R]
func Executor[R].GetWithExecutionAsync(fn func(exec Execution[R]) (R, error)) ExecutionResult[R]
func Executor[R].RunAsync(fn func() error) ExecutionResult[R]
func Executor[R].RunWithExecutionAsync(fn func(exec Execution[R]) error) ExecutionResult[R]
Type Parameters:
R: any ExecutionScheduledEvent indicates an execution was scheduled. The delay before the next execution attempt.ExecutionAttemptExecutionAttempt[R] AttemptStartTime returns the time that the most recent execution attempt started at. Attempts returns the number of execution attempts so far, including attempts that are currently in progress and
attempts that were blocked before being executed, such as by a CircuitBreaker or RateLimiter. These can include an initial
execution along with retries and hedges. Context returns the context configured for the execution, else context.Background if none was configured. For
executions involving a timeout or hedge, each attempt will get a separate child context. ElapsedAttemptTime returns the elapsed time since the last execution attempt began. ElapsedTime returns the elapsed time since initial execution attempt began. Executions returns the number of completed executions. Executions that are blocked, such as when a CircuitBreaker is
open, are not counted. Hedges returns the number of hedges that have been executed so far, including hedges that are currently in progress. IsFirstAttempt returns true when Attempts is 1, meaning this is the first execution attempt. IsHedge returns true when the execution is part of a hedged attempt. IsRetry returns true when Attempts is > 1, meaning the execution is being retried. LastError returns the error, if any, from the last execution attempt. LastResult returns the result, if any, from the last execution attempt. Retries returns the number of retries so far, including retries that are currently in progress. StartTime returns the time that the initial execution attempt started at.
ExecutionScheduledEvent : ExecutionAttempt[R]
ExecutionScheduledEvent : ExecutionInfo[R]
Type Parameters:
R: any Executor handles failures according to configured policies. See [NewExecutor] for details.
This type is concurrency safe. Get executes the fn until a successful result is returned or the configured policies are exceeded.
Any panic causes the execution to stop immediately without calling any event listeners. GetAsync executes the fn in a goroutine until a successful result is returned or the configured policies are exceeded.
Any panic causes the execution to stop immediately without calling any event listeners. GetWithExecution executes the fn until a successful result is returned or the configured policies are exceeded, while
providing an Execution to the fn.
Any panic causes the execution to stop immediately without calling any event listeners. GetWithExecutionAsync executes the fn in a goroutine until a successful result is returned or the configured policies
are exceeded, while providing an Execution to the fn.
Any panic causes the execution to stop immediately without calling any event listeners. OnDone registers the listener to be called when an execution is done. OnFailure registers the listener to be called when an execution fails. This occurs when the execution fails according
to some policy, and all policies have been exceeded. OnSuccess registers the listener to be called when an execution is successful. If multiple policies, are configured,
this handler is called when execution is done and all policies succeed. If all policies do not succeed, then the
OnFailure registered listener is called instead. Run executes the fn until successful or until the configured policies are exceeded.
Any panic causes the execution to stop immediately without calling any event listeners. RunAsync executes the fn in a goroutine until successful or until the configured policies are exceeded.
Any panic causes the execution to stop immediately without calling any event listeners. RunWithExecution executes the fn until successful or until the configured policies are exceeded, while providing an
Execution to the fn.
Any panic causes the execution to stop immediately without calling any event listeners. RunWithExecutionAsync executes the fn in a goroutine until successful or until the configured policies are exceeded,
while providing an Execution to the fn.
Any panic causes the execution to stop immediately without calling any event listeners. WithContext returns a new copy of the Executor with the ctx configured. Any executions created with the resulting
Executor will be canceled when the ctx is done. Executions can cooperate with cancellation by checking
Execution.Canceled or Execution.IsCanceled.
func NewExecutor[R](policies ...Policy[R]) Executor[R]
func Executor[R].OnDone(listener func(ExecutionDoneEvent[R])) Executor[R]
func Executor[R].OnFailure(listener func(ExecutionDoneEvent[R])) Executor[R]
func Executor[R].OnSuccess(listener func(ExecutionDoneEvent[R])) Executor[R]
func Executor[R].WithContext(ctx context.Context) Executor[R]
Type Parameters:
S: any
R: any FailurePolicyBuilder builds a Policy that allows configurable conditions to determine whether an execution is a failure.
- By default, any error is considered a failure and will be handled by the policy. You can override this by specifying
your own handle conditions. The default error handling condition will only be overridden by another condition that
handles errors such as Handle or HandleIf. Specifying a condition that only handles results, such as HandleResult
will not replace the default error handling condition.
- If multiple handle conditions are specified, any condition that matches an execution result or error will trigger
policy handling. HandleErrorTypes specifies the errors whose types should be handled as failures. Any execution errors or their
Unwrapped parents whose type matches any of the errs' types will be handled. This is similar to the check that
errors.As performs. HandleErrors specifies the errors to handle as failures. Any errs that evaluate to true for errors.Is and the
execution error will be handled. HandleIf specifies that a failure has occurred if the predicate matches the execution result or error. HandleResult specifies the results to handle as failures. Any result that evaluates to true for reflect.DeepEqual and
the execution result will be handled. This method is only considered when a result is returned from an execution, not
when an error is returned. OnFailure registers the listener to be called when the policy determines an execution attempt was a failure, and may
be handled. OnSuccess registers the listener to be called when the policy determines an execution attempt was a success.
Type Parameters:
R: any Get executes the fn, with failures being handled by the policies, until a successful result is returned or the
policies are exceeded.
Type Parameters:
R: any GetAsync executes the fn in a goroutine, with failures being handled by the policies, until a successful result is returned
or the policies are exceeded.
Type Parameters:
R: any GetWithExecution executes the fn, with failures being handled by the policies, until a successful result is returned
or the policies are exceeded.
Type Parameters:
R: any GetWithExecutionAsync executes the fn in a goroutine, with failures being handled by the policies, until a successful
result is returned or the policies are exceeded.
Type Parameters:
R: any NewExecutor creates and returns a new Executor for result type R that will handle failures according to the given
policies. The policies are composed around a func and will handle its results in reverse order. For example, consider:
failsafe.NewExecutor(fallback, retryPolicy, circuitBreaker).Get(fn)
This creates the following composition when executing a func and handling its result:
Fallback(RetryPolicy(CircuitBreaker(func)))
Run executes the fn, with failures being handled by the policies, until successful or until the policies are exceeded.
RunAsync executes the fn in a goroutine, with failures being handled by the policies, until successful or until the
policies are exceeded.
RunWithExecution executes the fn, with failures being handled by the policies, until successful or until the policies
are exceeded.
RunWithExecutionAsync executes the fn in a goroutine, with failures being handled by the policies, until successful or
until the policies are exceeded.
Package-Level Variables (only one)
ErrExecutionCanceled indicates that an execution was canceled by ExecutionResult.Cancel.
The pages are generated with Goldsv0.8.2. (GOOS=linux GOARCH=amd64)
Golds is a Go 101 project developed by Tapir Liu.
PR and bug reports are welcome and can be submitted to the issue list.
Please follow @zigo_101 (reachable from the left QR code) to get the latest news of Golds.
