shutdown

Documentation

Index

• func MaximumShutdownWait() time.Duration
• type Closable
• type ClosablePool
  • func NewClosablePool() *ClosablePool
  • func (c *ClosablePool) Add(tier int, closable Closable)
  • func (c *ClosablePool) Close(timeout time.Duration) error
• type Signaller
  • func NewSignaller() *Signaller
  • func (s *Signaller) CloseAtLeisure()
  • func (s *Signaller) CloseAtLeisureChan() <-chan struct{}
  • func (s *Signaller) CloseAtLeisureCtx(ctx context.Context) (context.Context, context.CancelFunc)
  • func (s *Signaller) CloseNow()
  • func (s *Signaller) CloseNowChan() <-chan struct{}
  • func (s *Signaller) CloseNowCtx(ctx context.Context) (context.Context, context.CancelFunc)
  • func (s *Signaller) HasClosed() bool
  • func (s *Signaller) HasClosedChan() <-chan struct{}
  • func (s *Signaller) HasClosedCtx(ctx context.Context) (context.Context, context.CancelFunc)
  • func (s *Signaller) ShouldCloseAtLeisure() bool
  • func (s *Signaller) ShouldCloseNow() bool
  • func (s *Signaller) ShutdownComplete()

Functions

func MaximumShutdownWait

func MaximumShutdownWait() time.Duration

MaximumShutdownWait is a magic number determining the maximum length of time that a component should be willing to wait for a child to finish shutting down before it can give up and exit.

This wait time is largely symbolic, if a component blocks for anything more than a few minutes then it has failed in its duty to gracefully terminate.

However, it's still necessary for components to provide some measure of time that they're willing to wait for with the current mechanism (WaitForClose), therefore we provide a very large duration, and since this is a magic number I've defined it once and exposed as a function, allowing us to more easily identify these cases and refactor them in the future.

Types

type Closable

type Closable interface {
	// CloseAsync triggers the shut down of this component but should not block
	// the calling goroutine.
	CloseAsync()

	// WaitForClose is a blocking call to wait until the component has finished
	// shutting down and cleaning up resources.
	WaitForClose(timeout time.Duration) error
}

Closable defines a type that can be safely closed down and cleaned up. This interface is required for many components within Benthos, but if your implementation is stateless and does not require shutting down then this interface can be implemented with empty shims.

type ClosablePool

type ClosablePool struct {
	// contains filtered or unexported fields
}

ClosablePool keeps a reference to a pool of closable types and closes them in tiers.

func NewClosablePool

func NewClosablePool() *ClosablePool

NewClosablePool creates a fresh pool of closable types.

func (*ClosablePool) Add

func (c *ClosablePool) Add(tier int, closable Closable)

Add adds a closable type to the pool, tiers are used to partition and order the closing of types (starting at the lowest tier and working upwards). Closable types in a single tier are closed in the order that they are added.

func (*ClosablePool) Close

func (c *ClosablePool) Close(timeout time.Duration) error

Close attempts to close and clean up all stored closables in the determined order. If the timeout is met whilst working through the pool there is no indication of how far the pool has been progressed, thus this timeout should only be used for preventing severe blocking of a service.

type Signaller

type Signaller struct {
	// contains filtered or unexported fields
}

Signaller is a mechanism owned by components that support graceful shut down and is used as a way to signal from outside that any goroutines owned by the component should begin to close.

Shutting down can happen in two tiers of urgency, the first is to terminate "at leisure", meaning if you're in the middle of something it's okay to do that first before terminating, but please do not commit to new work.

The second tier is immediate, where you need to clean up resources and terminate as soon as possible, regardless of any tasks that you are currently attempting to finish.

Finally, there is also a signal of having closed down, which is made by the component and can be used from outside to determine whether the component has finished terminating.

func NewSignaller

func NewSignaller() *Signaller

NewSignaller creates a new signaller.

func (*Signaller) CloseAtLeisure

func (s *Signaller) CloseAtLeisure()

CloseAtLeisure signals to the owner of this Signaller that it should terminate at its own leisure, meaning it's okay to complete any tasks that are in progress but no new work should be started.

func (*Signaller) CloseAtLeisureChan

func (s *Signaller) CloseAtLeisureChan() <-chan struct{}

CloseAtLeisureChan returns a channel that will be closed when the signal to shut down either at leisure or immediately has been made.

func (*Signaller) CloseAtLeisureCtx

func (s *Signaller) CloseAtLeisureCtx(ctx context.Context) (context.Context, context.CancelFunc)

CloseAtLeisureCtx returns a context.Context that will be terminated when either the provided context is cancelled or the signal to shut down either at leisure or immediately has been made.

func (*Signaller) CloseNow

func (s *Signaller) CloseNow()

CloseNow signals to the owner of this Signaller that it should terminate right now regardless of any in progress tasks.

func (*Signaller) CloseNowChan

func (s *Signaller) CloseNowChan() <-chan struct{}

CloseNowChan returns a channel that will be closed when the signal to shut down immediately has been made.

func (*Signaller) CloseNowCtx

func (s *Signaller) CloseNowCtx(ctx context.Context) (context.Context, context.CancelFunc)

CloseNowCtx returns a context.Context that will be terminated when either the provided context is cancelled or the signal to shut down immediately has been made.

func (*Signaller) HasClosed

func (s *Signaller) HasClosed() bool

HasClosed returns true if the signaller has received the signal that the component has terminated.

func (*Signaller) HasClosedChan

func (s *Signaller) HasClosedChan() <-chan struct{}

HasClosedChan returns a channel that will be closed when the signal that the component has terminated has been made.

func (*Signaller) HasClosedCtx

func (s *Signaller) HasClosedCtx(ctx context.Context) (context.Context, context.CancelFunc)

HasClosedCtx returns a context.Context that will be cancelled when either the provided context is cancelled or the signal that the component has shut down has been made.

func (*Signaller) ShouldCloseAtLeisure

func (s *Signaller) ShouldCloseAtLeisure() bool

ShouldCloseAtLeisure returns true if the signaller has received the signal to shut down at leisure or immediately.

func (*Signaller) ShouldCloseNow

func (s *Signaller) ShouldCloseNow() bool

ShouldCloseNow returns true if the signaller has received the signal to shut down immediately.

func (*Signaller) ShutdownComplete

func (s *Signaller) ShutdownComplete()

ShutdownComplete is a signal made by the component that it and all of its owned resources have terminated.