queue

Documentation

Overview

Package queue implements a dynamic FIFO queue with a fixed upper bound and a flexible quota mechanism to handle bursty load.

Index

• Variables
• type Options
• type Queue
  • func New(opts Options) (*Queue, error)
  • func (q *Queue) Add(item interface{}) error
  • func (q *Queue) Close() error
  • func (q *Queue) Remove() (interface{}, bool)
  • func (q *Queue) Wait(ctx context.Context) (interface{}, error)

Variables

var (
	// ErrQueueFull is returned by the Add method of a queue when the queue has
	// reached its hard capacity limit.
	ErrQueueFull = errors.New("queue is full")

	// ErrNoCredit is returned by the Add method of a queue when the queue has
	// exceeded its soft quota and there is insufficient burst credit.
	ErrNoCredit = errors.New("insufficient burst credit")

	// ErrQueueClosed is returned by the Add method of a closed queue, and by
	// the Wait method of a closed empty queue.
	ErrQueueClosed = errors.New("queue is closed")
)

Types

type Options

type Options struct {
	// The maximum number of items the queue will ever be permitted to hold.
	// This value must be positive, and greater than or equal to SoftQuota. The
	// hard limit is fixed and does not change as the queue is used.
	//
	// The hard limit should be chosen to exceed the largest burst size expected
	// under normal operating conditions.
	HardLimit int

	// The initial expected maximum number of items the queue should contain on
	// an average workload. If this value is zero, it is initialized to the hard
	// limit. The soft quota is adjusted from the initial value dynamically as
	// the queue is used.
	SoftQuota int

	// The initial burst credit score.  This value must be greater than or equal
	// to zero. If it is zero, the soft quota is used.
	BurstCredit float64
}

Options are the initial settings for a Queue.

type Queue

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

A Queue is a limited-capacity FIFO queue of arbitrary data items.

A queue has a soft quota and a hard limit on the number of items that may be contained in the queue. Adding items in excess of the hard limit will fail unconditionally.

For items in excess of the soft quota, a credit system applies: Each queue maintains a burst credit score. Adding an item in excess of the soft quota costs 1 unit of burst credit. If there is not enough burst credit, the add will fail.

The initial burst credit is assigned when the queue is constructed. Removing items from the queue adds additional credit if the resulting queue length is less than the current soft quota. Burst credit is capped by the hard limit.

A Queue is safe for concurrent use by multiple goroutines.

func New

func New(opts Options) (*Queue, error)

New constructs a new empty queue with the specified options. It reports an error if any of the option values are invalid.

func (*Queue) Add

func (q *Queue) Add(item interface{}) error

Add adds item to the back of the queue. It reports an error and does not enqueue the item if the queue is full or closed, or if it exceeds its soft quota and there is not enough burst credit.

func (*Queue) Close

func (q *Queue) Close() error

Close closes the queue. After closing, any further Add calls will report an error, but items that were added to the queue prior to closing will still be available for Remove and Wait. Wait will report an error without blocking if it is called on a closed, empty queue.

func (*Queue) Remove

func (q *Queue) Remove() (interface{}, bool)

Remove removes and returns the frontmost (oldest) item in the queue and reports whether an item was available. If the queue is empty, Remove returns nil, false.

func (*Queue) Wait

func (q *Queue) Wait(ctx context.Context) (interface{}, error)

Wait blocks until q is non-empty or closed, and then returns the frontmost (oldest) item from the queue. If ctx ends before an item is available, Wait returns a nil value and a context error. If the queue is closed while it is still empty, Wait returns nil, ErrQueueClosed.