bulkhead

Documentation

Overview

Package bulkhead provides a Bulkhead policy.

Index

• Variables
• type Builder
  • func NewBuilder[R any](maxConcurrency uint) Builder[R]
• type Bulkhead
  • func New[R any](maxConcurrency uint) Bulkhead[R]

Variables

var ErrFull = errors.New("bulkhead full")

ErrFull is returned when an execution is attempted against a Bulkhead that is full.

Types

type Builder

type Builder[R any] interface {
	// WithMaxWaitTime configures the maxWaitTime to wait for permits to be available.
	WithMaxWaitTime(maxWaitTime time.Duration) Builder[R]

	// OnFull registers the listener to be called when the bulkhead is full.
	OnFull(listener func(event failsafe.ExecutionEvent[R])) Builder[R]

	// Build returns a new Bulkhead using the builder's configuration.
	Build() Bulkhead[R]
}

Builder builds Bulkhead instances.

R is the execution result type. This type is not concurrency safe.

func NewBuilder

func NewBuilder[R any](maxConcurrency uint) Builder[R]

NewBuilder returns a Builder for execution result type R which builds Timeouts for the timeoutDelay.

type Bulkhead

type Bulkhead[R any] interface {
	failsafe.ResultAgnosticPolicy[R]

	// AcquirePermit attempts to acquire a permit to perform an execution within the Bulkhead, waiting until one is
	// available or the execution is canceled. Returns context.Canceled if the ctx is canceled. Callers should call
	// ReleasePermit to release a successfully acquired permit back to the Bulkhead.
	//
	// ctx may be nil.
	AcquirePermit(ctx context.Context) error

	// AcquirePermitWithMaxWait attempts to acquire a permit to perform an execution within the Bulkhead, waiting up to the
	// maxWaitTime until one is available or the ctx is canceled. Returns ErrFull if a permit could not be acquired
	// in time. Returns context.Canceled if the ctx is canceled. Callers should call ReleasePermit to release a successfully
	// acquired permit back to the Bulkhead.
	//
	// ctx may be nil.
	AcquirePermitWithMaxWait(ctx context.Context, maxWaitTime time.Duration) error

	// TryAcquirePermit tries to acquire a permit to perform an execution within the Bulkhead, returning immediately without
	// waiting. Returns true if the permit was acquired, else false. Callers should call ReleasePermit to release a
	// successfully acquired permit back to the Bulkhead.
	TryAcquirePermit() bool

	// ReleasePermit releases an execution permit back to the Bulkhead.
	ReleasePermit()
}

Bulkhead is a policy that restricts concurrent executions as a way of preventing system overload.

R is the execution result type. This type is concurrency safe.

func New

func New[R any](maxConcurrency uint) Bulkhead[R]

New returns a new Bulkhead for execution result type R and the maxConcurrency.