pool

Documentation

Overview

Package pool contains an implementation of a hierarchical, weighted selection pool.

Index

• type Entry
• type Pool
  • func (p *Pool) Add(e Entry)
  • func (p *Pool) All() []Entry
  • func (p *Pool) IsOverloaded(e Entry) bool
  • func (p *Pool) Len() int
  • func (p *Pool) Load(e Entry) int
  • func (p *Pool) MarshalYAML() (interface{}, error)
  • func (p *Pool) Peek() *Token
  • func (p *Pool) Pick() *Token
  • func (p *Pool) PickLoad(load int) *Token
  • func (p *Pool) Rebalance()
  • func (p *Pool) Remove(e Entry)
  • func (p *Pool) Wait(ctx context.Context, load int) (*Token, error)
• type Token
  • func (t *Token) Entry() Entry
  • func (t *Token) Release() bool

Types

type Entry

type Entry interface {
	// MaxLoad allows an entry to specify the number of times that it
	// can be concurrently picked from the pool.
	//
	// The MaxLoad value will be re-checked when an Entry is about to be
	// picked, which provides callers with the opportunity to provide
	// dynamic admission control.
	//
	// If MaxLoad() is less than 1, the Entry can no longer be picked,
	// however this will not invalidate any currently-issued Tokens.
	MaxLoad() int
	// Tier establishes equivalence classes within the pool.
	// Lower-numbered tiers are given higher priority when selecting an
	// entry.
	Tier() int
}

An Entry represents something that can be picked out of a Pool.

type Pool

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

A Pool provides a weighted, tiered, round-robin selection mechanism for instances of pool.Entry.

A Pool must not be copied after first use.

func (*Pool) Add

func (p *Pool) Add(e Entry)

Add enrolls the given Entry into the Pool. It is a no-op to add the same Entry more than once.

func (*Pool) All

func (p *Pool) All() []Entry

All returns all entries currently in the Pool, sorted by preference.

func (*Pool) IsOverloaded

func (p *Pool) IsOverloaded(e Entry) bool

IsOverloaded returns true if the Entry is known to have a higher load than its configured maximum (e.g. when draining).

func (*Pool) Len

func (p *Pool) Len() int

Len returns the total size of the pool.

func (*Pool) Load

func (p *Pool) Load(e Entry) int

Load returns the currently outstanding load count on the entry.

func (*Pool) MarshalYAML

func (p *Pool) MarshalYAML() (interface{}, error)

MarshalYAML dumps the current status of the Pool into a YAML structure.

func (*Pool) Peek

func (p *Pool) Peek() *Token

Peek is a shortcut for PickLoad(0).

This effectively returns the best-guess as to the next Entry to be returned from the pool.

func (*Pool) Pick

func (p *Pool) Pick() *Token

Pick is a shortcut for PickLoad(1).

func (*Pool) PickLoad

func (p *Pool) PickLoad(load int) *Token

PickLoad will return a Token that provides access to an Entry in the pool that has at least the requested load available.

The Token exists to act as a reference-counter on the Entry to ensure that no more than Entry.MaxLoad() Tokens exist for than entry when Pick is called.

Token.Release() should be called once the Entry is no longer needed by the caller. A GC finalizer will be set up to avoid leaks, but the timing of the GC cannot be relied upon for correctness.

func (*Pool) Rebalance

func (p *Pool) Rebalance()

Rebalance will re-prioritize all entries based on their Load and Tier. This method only needs to be called if entries are expected to be picked infrequently, as their status will be sampled during a call to Pick().

func (*Pool) Remove

func (p *Pool) Remove(e Entry)

Remove discards the given entry from the pool.

Any currently-issued Tokens for the Entry will remain valid, but became no-ops.

func (*Pool) Wait

func (p *Pool) Wait(ctx context.Context, load int) (*Token, error)

Wait is a blocking version of Pick() than can be interrupted by Context cancellation.

type Token

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

A Token represents the intent to use an Entry in the Pool. Tokens should be released by callers in order to avoid delaying the return of an entry to a pool.

func (*Token) Entry

func (t *Token) Entry() Entry

Entry retrieves the Entry that is tracked by the token. This method may be called as many times as desired until Release is called. Once the Token has been released, this method will return nil.

func (*Token) Release

func (t *Token) Release() bool

Release will return the associated Entry to the Pool.

Release will return true the first time it is called and then false thereafter.