pool

Documentation

Index

• Variables
• type Pool
  • func (p *Pool) ActiveCount() int
  • func (p *Pool) Close() error
  • func (p *Pool) Get() io.Closer
  • func (p *Pool) IdleCount() int
  • func (p *Pool) Put(c io.Closer) error
  • func (p *Pool) Stats() Stats
• type Stats

Variables

var ErrPoolExhausted = errors.New("pool_exhausted")

ErrPoolExhausted is returned from a pool connection method (Do, Send, Receive, Flush, Err) when the maximum number of database connections in the pool has been reached.

Types

type Pool

type Pool struct {
	// Dial is an application supplied function for creating and configuring a
	// connection.
	//
	// The connection returned from Dial must not be in a special state
	// (subscribed to pubsub channel, transaction started, ...).
	Dial func() (io.Closer, error)

	// TestOnBorrow is an optional application supplied function for checking
	// the health of an idle connection before the connection is used again by
	// the application. Argument t is the time that the connection was returned
	// to the pool. If the function returns an error, then the connection is
	// closed.
	TestOnBorrow func(c io.Closer, t time.Time) error

	// Maximum number of idle connections in the pool.
	MaxIdle int

	// Maximum number of connections allocated by the pool at a given time.
	// When zero, there is no limit on the number of connections in the pool.
	MaxActive int

	// Close connections after remaining idle for this duration. If the value
	// is zero, then idle connections are not closed. Applications should set
	// the timeout to a value less than the server's timeout.
	IdleTimeout time.Duration

	// If Wait is true and the pool is at the MaxActive limit, then Get() waits
	// for a connection to be returned to the pool before returning.
	Wait bool

	// Close connections older than this duration. If the value is zero, then
	// the pool does not close connections based on age.
	MaxConnLifetime time.Duration
	// contains filtered or unexported fields
}

Pool maintains a pool of connections. The application calls the Get method to get a connection from the pool and the connection's Close method to return the connection's resources to the pool.

The following example shows how to use a pool in a web application. The application creates a pool at application startup and makes it available to request handlers using a package level variable. The pool configuration used here is an example, not a recommendation.

func newPool(addr string) io.Closer {
  return &pool.Pool{
    MaxIdle: 3,
    IdleTimeout: 240 * time.Second,
    Dial: func () (io.Closer, error) { return redis.Dial("tcp", addr) },
  }
}

var (
  pool *pool.Pool
  redisServer = flag.String("redisServer", ":6379", "")
)

func main() {
  flag.Parse()
  pool = newPool(*redisServer)
  ...
}

A request handler gets a connection from the pool and closes the connection when the handler is done:

func serveHome(w http.ResponseWriter, r *http.Request) {
    conn := pool.Get()
    defer pool.Put(conn)
    ...
}

Use the Dial function to authenticate connections with the AUTH command or select a database with the SELECT command:

pool := &pool.Pool{
  // Other pool configuration not shown in this example.
  Dial: func () (io.Closer, error) {
    c, err := redis.Dial("tcp", server)
    if err != nil {
      return nil, err
    }
    if _, err := c.Do("AUTH", password); err != nil {
      c.Close()
      return nil, err
    }
    if _, err := c.Do("SELECT", db); err != nil {
      c.Close()
      return nil, err
    }
    return c, nil
  },
}

Use the TestOnBorrow function to check the health of an idle connection before the connection is returned to the application. This example PINGs connections that have been idle more than a minute:

pool := &pool.Pool{
  // Other pool configuration not shown in this example.
  TestOnBorrow: func(c io.Closer, t time.Time) error {
    if time.Since(t) < time.Minute {
      return nil
    }
    _, err := c.Do("PING")
    return err
  },
}

func (*Pool) ActiveCount

func (p *Pool) ActiveCount() int

ActiveCount returns the number of connections in the pool. The count includes idle connections and connections in use.

func (*Pool) Close

func (p *Pool) Close() error

Close releases the resources used by the pool.

func (*Pool) Get

func (p *Pool) Get() io.Closer

Get gets a connection. The application must Put the returned connection to Pool. Note: This method may return nil.

func (*Pool) IdleCount

func (p *Pool) IdleCount() int

IdleCount returns the number of idle connections in the pool.

func (*Pool) Put

func (p *Pool) Put(c io.Closer) error

Put back the connection to Pool

func (*Pool) Stats

func (p *Pool) Stats() Stats

Stats returns pool's statistics.

type Stats

type Stats struct {
	// ActiveCount is the number of connections in the pool. The count includes
	// idle connections and connections in use.
	ActiveCount int
	// IdleCount is the number of idle connections in the pool.
	IdleCount int
}

Stats contains pool statistics.