workpool

package
v4.2.13-dev.1+incompat... Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 6, 2021 License: Apache-2.0 Imports: 3 Imported by: 0

Documentation

Overview

Package workpool provies the `Pool` type which functions as a means of managing the number of concurrent workers, grouped by key. You can think of this type as functioning like a collection of semaphores, except that multiple distinct resources may exist (distinguished by keys), and the target concurrent worker count may change at runtime. The basic usage pattern is as follows:

1. The desired number of workers for a given key is specified or updated via Pool.Set.

2. Workers are spawned as leases become available on Pool.Acquire.

3. Workers relenquish their leases when they finish their work by calling Lease.Release.

4. New leases become available as old leases are relenquished, or as the target concurrent lease count increases.

This is a generalization of logic originally written to manage the number of concurrent reversetunnel agents per proxy endpoint.

Example
pool := NewPool(context.TODO())
defer pool.Stop()
// create two keys with different target counts
pool.Set("spam", 2)
pool.Set("eggs", 1)
// track how many workers are spawned for each key
counts := make(map[string]int)
var mu sync.Mutex
var wg sync.WaitGroup
for i := 0; i < 12; i++ {
	wg.Add(1)
	go func() {
		lease := <-pool.Acquire()
		defer lease.Release()
		mu.Lock()
		counts[lease.Key().(string)]++
		mu.Unlock()
		// in order to demonstrate the differing spawn rates we need
		// work to take some time, otherwise pool will end up granting
		// leases in a "round robin" fashion.
		time.Sleep(time.Millisecond * 10)
		wg.Done()
	}()
}
wg.Wait()
// exact counts will vary, but leases with key `spam`
// will end up being generated approximately twice as
// often as leases with key `eggs`.
fmt.Println(counts["spam"] > counts["eggs"]) 
Output:

true

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Counts

type Counts struct {
	// Target is the number of active leases that we would
	// like to converge toward.
	Target uint64
	// Active is the current active lease count.
	Active uint64
}

Counts holds the target and active counts for a key/group.

type Lease

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

Lease grants access to a resource or group. When the lease is received, work can begin. Leases are held by workers and must be released when the worker has finished its work.

func (Lease) ID

func (l Lease) ID() uint64

ID returns the unique ID of this lease.

func (Lease) IsZero

func (l Lease) IsZero() bool

IsZero checks if this is the zero value of Lease.

func (Lease) Key

func (l Lease) Key() interface{}

Key returns the key that this lease is associated with.

func (Lease) Release

func (l Lease) Release()

Release relenquishes this lease. Each lease is unique, so double-calling Release on the same Lease has no effect.

type Pool

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

Pool manages a collection of work groups by key and is the primary means by which groups are managed. Each work group has an adjustable target value which is the number of target leases which should be active for the given group.

func NewPool

func NewPool(ctx context.Context) *Pool

func (*Pool) Acquire

func (p *Pool) Acquire() <-chan Lease

Acquire is the channel which must be received on to acquire new leases. Each lease acquired in this way *must* have its Release method called when the lease is no longer needed.

func (*Pool) Done

func (p *Pool) Done() <-chan struct{}

Done signals pool closure.

func (*Pool) Get

func (p *Pool) Get(key interface{}) Counts

Get gets the current counts for the specified key.

func (*Pool) Set

func (p *Pool) Set(key interface{}, target uint64)

Set sets the target for the specified key.

func (*Pool) Stop

func (p *Pool) Stop()

Stop permanently halts all associated groups.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL