pool

README

Common Go resource pooling code shared between my projects

License

This project is subject to the the MIT License. See LICENSE information for details.

Documentation

Overview

Package pool provides functionality for pooling resources which require an open-and-close lifecycle (e.g. network connections).

Index

• Variables
• type Resource
  • func (r *Resource[R]) Get() R
  • func (r *Resource[R]) Release()
  • func (r *Resource[R]) Reset()
• type ResourceFactory
• type Resources
  • func NewResourcePool[R io.Closer](name string, factory ResourceFactory[R]) *Resources[R]
  • func (p *Resources[R]) Close() error
  • func (p *Resources[R]) Get(ctx context.Context) (*Resource[R], error)
  • func (p *Resources[R]) SetMaxIdleResources(n int)
  • func (p *Resources[R]) SetMaxTotalResources(n int)
  • func (p *Resources[R]) SetResourceMaxIdleTime(d time.Duration)
  • func (p *Resources[R]) SetResourceMaxLifetime(d time.Duration)
  • func (p *Resources[R]) Shutdown(ctx context.Context) error

Variables

var ErrPoolClosed error = errors.New("pool closed")

ErrPoolClosed indicates this pool instance has already been closed.

var ErrPoolClosing error = errors.New("pool closing")

ErrPoolClosing indicates this pool instance is currently shutting down and about to be closed.

var ErrPoolExhausted error = errors.New("pool exhausted")

ErrPoolExhausted indicates the maximum allowed number of resources for this pool instance is in use.

Types

type Resource

type Resource[R io.Closer] struct {
	// contains filtered or unexported fields
}

Resource represents a resource pool entry, as returned by Resources.Get.

func (*Resource[R]) Get

func (r *Resource[R]) Get() R

Get retrieves the resource managed by this resource entry instance.

func (*Resource[R]) Release

func (r *Resource[R]) Release()

Release transfers ownership of the resource back to the pool.

func (*Resource[R]) Reset

func (r *Resource[R]) Reset()

Reset marks the resource as to be closed and re-created during release.

type ResourceFactory

type ResourceFactory[R io.Closer] interface {
	// New creates a new resource instance.
	New(ctx context.Context) (R, error)
}

ResourceFactory interface is used to create new resource instances on demand.

type Resources

type Resources[R io.Closer] struct {
	// contains filtered or unexported fields
}

Resources provides resource pool functionality for the given resource type.

func NewResourcePool

func NewResourcePool[R io.Closer](name string, factory ResourceFactory[R]) *Resources[R]

NewResourcePool creates a new resource pool using the given name and factory interface.

func (*Resources[R]) Close

func (p *Resources[R]) Close() error

Close closes the pool by closing any idle resource in the pool.

func (*Resources[R]) Get

func (p *Resources[R]) Get(ctx context.Context) (*Resource[R], error)

Get aquires a resource instance from the pool.

The requested resource is either taken from the existing idle queue or a new instance is created by invoking the factory interface given during pool creation. If a total resource limit has been set and the limit is reached, ErrPoolExhausted is returned.

func (*Resources[R]) SetMaxIdleResources

func (p *Resources[R]) SetMaxIdleResources(n int)

SetMaxIdleResources sets the maximum number of idle resource instances contained in the pool.

If n <= 0, then there is no limit. The default value is 0 (no limit).

func (*Resources[R]) SetMaxTotalResources

func (p *Resources[R]) SetMaxTotalResources(n int)

SetMaxTotalResources sets the maximum total number of resource instances contained in the pool.

If n <= 0, then there is no limit. The default value is 0 (no limit).

func (*Resources[R]) SetResourceMaxIdleTime

func (p *Resources[R]) SetResourceMaxIdleTime(d time.Duration)

SetResourceMaxIdleTime sets the timeout, after which an idle resource instance is closed.

If d <= 0, then there is no timeout. The default value is 0 (no timeout).

func (*Resources[R]) SetResourceMaxLifetime

func (p *Resources[R]) SetResourceMaxLifetime(d time.Duration)

SetResourceMaxLifetime sets the timeout, after a resource instance is closed.

If d <= 0, then there is no timeout. The default value is 0 (no timeout).

func (*Resources[R]) Shutdown

func (p *Resources[R]) Shutdown(ctx context.Context) error

Shutdown shuts down the pool gracefully by waiting for the release of any currently active resource.