pools

Documentation

Overview

Package pools provides functionality to manage and reuse resources like connections.

Index

• Variables
• type Factory
• type Numbered
  • func NewNumbered() *Numbered
  • func (nu *Numbered) Get(id int64, purpose string) (val interface{}, err error)
  • func (nu *Numbered) GetIdle(timeout time.Duration, purpose string) (vals []interface{})
  • func (nu *Numbered) GetOutdated(age time.Duration, purpose string) (vals []interface{})
  • func (nu *Numbered) Put(id int64)
  • func (nu *Numbered) Register(id int64, val interface{}) error
  • func (nu *Numbered) Size() (size int64)
  • func (nu *Numbered) StatsJSON() string
  • func (nu *Numbered) Unregister(id int64)
  • func (nu *Numbered) WaitForEmpty()
• type Resource
• type ResourcePool
  • func NewResourcePool(factory Factory, capacity, maxCap int, idleTimeout time.Duration) *ResourcePool
  • func (rp *ResourcePool) Available() int64
  • func (rp *ResourcePool) Capacity() int64
  • func (rp *ResourcePool) Close()
  • func (rp *ResourcePool) Get() (resource Resource, err error)
  • func (rp *ResourcePool) IdleTimeout() time.Duration
  • func (rp *ResourcePool) IsClosed() (closed bool)
  • func (rp *ResourcePool) MaxCap() int64
  • func (rp *ResourcePool) Put(resource Resource)
  • func (rp *ResourcePool) SetCapacity(capacity int) error
  • func (rp *ResourcePool) SetIdleTimeout(idleTimeout time.Duration)
  • func (rp *ResourcePool) Stats() (capacity, available, maxCap, waitCount int64, ...)
  • func (rp *ResourcePool) StatsJSON() string
  • func (rp *ResourcePool) TryGet() (resource Resource, err error)
  • func (rp *ResourcePool) WaitCount() int64
  • func (rp *ResourcePool) WaitTime() time.Duration
• type RoundRobin
  • func NewRoundRobin(capacity int, idleTimeout time.Duration) *RoundRobin
  • func (rr *RoundRobin) Close()
  • func (rr *RoundRobin) Get() (resource Resource, err error)
  • func (rr *RoundRobin) IsClosed() bool
  • func (rr *RoundRobin) Open(factory Factory)
  • func (rr *RoundRobin) Put(resource Resource)
  • func (rr *RoundRobin) SetCapacity(capacity int) error
  • func (rr *RoundRobin) SetIdleTimeout(idleTimeout time.Duration)
  • func (rr *RoundRobin) Stats() (size, capacity, available, waitCount int64, ...)
  • func (rr *RoundRobin) StatsJSON() string
  • func (rr *RoundRobin) TryGet() (resource Resource, err error)

Variables

var (
	CLOSED_ERR = fmt.Errorf("ResourcePool is closed")
)

Types

type Factory

type Factory func() (Resource, error)

Factory is a function that can be used to create a resource.

type Numbered

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

Numbered allows you to manage resources by tracking them with numbers. There are no interface restrictions on what you can track.

func NewNumbered

func NewNumbered() *Numbered

func (*Numbered) Get

func (nu *Numbered) Get(id int64, purpose string) (val interface{}, err error)

Get locks the resource for use. It accepts a purpose as a string. If it cannot be found, it returns a "not found" error. If in use, it returns a "in use: purpose" error.

func (*Numbered) GetIdle

func (nu *Numbered) GetIdle(timeout time.Duration, purpose string) (vals []interface{})

GetIdle returns a list of resurces that have been idle for longer than timeout, and locks them. It does not return any resources that are already locked.

func (*Numbered) GetOutdated

func (nu *Numbered) GetOutdated(age time.Duration, purpose string) (vals []interface{})

GetOutdated returns a list of resources that are older than age, and locks them. It does not return any resources that are already locked.

func (*Numbered) Put

func (nu *Numbered) Put(id int64)

Put unlocks a resource for someone else to use.

func (*Numbered) Register

func (nu *Numbered) Register(id int64, val interface{}) error

Register starts tracking a resource by the supplied id. It does not lock the object. It returns an error if the id already exists.

func (*Numbered) Size

func (nu *Numbered) Size() (size int64)

func (*Numbered) StatsJSON

func (nu *Numbered) StatsJSON() string

func (*Numbered) Unregister

func (nu *Numbered) Unregister(id int64)

Unregiester forgets the specified resource. If the resource is not present, it's ignored.

func (*Numbered) WaitForEmpty

func (nu *Numbered) WaitForEmpty()

WaitForEmpty returns as soon as the pool becomes empty

type Resource

type Resource interface {
	Close()
}

Every resource needs to suport the Resource interface. Thread synchronization between Close() and IsClosed() is the responsibility the caller.

type ResourcePool

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

ResourcePool allows you to use a pool of resources.

func NewResourcePool

func NewResourcePool(factory Factory, capacity, maxCap int, idleTimeout time.Duration) *ResourcePool

NewResourcePool creates a new ResourcePool pool. capacity is the initial capacity of the pool. maxCap is the maximum capacity. If a resource is unused beyond idleTimeout, it's discarded. An idleTimeout of 0 means that there is no timeout.

func (*ResourcePool) Available

func (rp *ResourcePool) Available() int64

func (*ResourcePool) Capacity

func (rp *ResourcePool) Capacity() int64

func (*ResourcePool) Close

func (rp *ResourcePool) Close()

Close empties the pool calling Close on all its resources. You can call Close while there are outstanding resources. It waits for all resources to be returned (Put). After a Close, Get and TryGet are not allowed.

func (*ResourcePool) Get

func (rp *ResourcePool) Get() (resource Resource, err error)

Get will return the next available resource. If capacity has not been reached, it will create a new one using the factory. Otherwise, it will indefinitely wait till the next resource becomes available.

func (*ResourcePool) IdleTimeout

func (rp *ResourcePool) IdleTimeout() time.Duration

func (*ResourcePool) IsClosed

func (rp *ResourcePool) IsClosed() (closed bool)

func (*ResourcePool) MaxCap

func (rp *ResourcePool) MaxCap() int64

func (*ResourcePool) Put

func (rp *ResourcePool) Put(resource Resource)

Put will return a resource to the pool. For every successful Get, a corresponding Put is required. If you no longer need a resource, you will need to call Put(nil) instead of returning the closed resource. The will eventually cause a new resource to be created in its place.

func (*ResourcePool) SetCapacity

func (rp *ResourcePool) SetCapacity(capacity int) error

SetCapacity changes the capacity of the pool. You can use it to shrink or expand, but not beyond the max capacity. If the change requires the pool to be shrunk, SetCapacity waits till the necessary number of resources are returned to the pool. A SetCapacity of 0 is equivalent to closing the ResourcePool.

func (*ResourcePool) SetIdleTimeout

func (rp *ResourcePool) SetIdleTimeout(idleTimeout time.Duration)

func (*ResourcePool) Stats

func (rp *ResourcePool) Stats() (capacity, available, maxCap, waitCount int64, waitTime, idleTimeout time.Duration)

func (*ResourcePool) StatsJSON

func (rp *ResourcePool) StatsJSON() string

func (*ResourcePool) TryGet

func (rp *ResourcePool) TryGet() (resource Resource, err error)

TryGet will return the next available resource. If none is available, and capacity has not been reached, it will create a new one using the factory. Otherwise, it will return nil with no error.

func (*ResourcePool) WaitCount

func (rp *ResourcePool) WaitCount() int64

func (*ResourcePool) WaitTime

func (rp *ResourcePool) WaitTime() time.Duration

type RoundRobin

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

RoundRobin is deprecated. Use ResourcePool instead. RoundRobin allows you to use a pool of resources in a round robin fashion.

func NewRoundRobin

func NewRoundRobin(capacity int, idleTimeout time.Duration) *RoundRobin

NewRoundRobin creates a new RoundRobin pool. capacity is the maximum number of resources RoundRobin will create. factory will be the function used to create resources. If a resource is unused beyond idleTimeout, it's discarded.

func (*RoundRobin) Close

func (rr *RoundRobin) Close()

Close empties the pool calling Close on all its resources. It waits for all resources to be returned (Put).

func (*RoundRobin) Get

func (rr *RoundRobin) Get() (resource Resource, err error)

Get will return the next available resource. If none is available, and capacity has not been reached, it will create a new one using the factory. Otherwise, it will indefinitely wait till the next resource becomes available.

func (*RoundRobin) IsClosed

func (rr *RoundRobin) IsClosed() bool

func (*RoundRobin) Open

func (rr *RoundRobin) Open(factory Factory)

Open starts allowing the creation of resources

func (*RoundRobin) Put

func (rr *RoundRobin) Put(resource Resource)

Put will return a resource to the pool. You MUST return every resource to the pool, even if it's closed. If a resource is closed, you should call Put(nil).

func (*RoundRobin) SetCapacity

func (rr *RoundRobin) SetCapacity(capacity int) error

Set capacity changes the capacity of the pool. You can use it to expand or shrink.

func (*RoundRobin) SetIdleTimeout

func (rr *RoundRobin) SetIdleTimeout(idleTimeout time.Duration)

func (*RoundRobin) Stats

func (rr *RoundRobin) Stats() (size, capacity, available, waitCount int64, waitTime, idleTimeout time.Duration)

func (*RoundRobin) StatsJSON

func (rr *RoundRobin) StatsJSON() string

func (*RoundRobin) TryGet

func (rr *RoundRobin) TryGet() (resource Resource, err error)

TryGet will return the next available resource. If none is available, and capacity has not been reached, it will create a new one using the factory. Otherwise, it will return nil with no error.