pool

README

Pool

Connection pool for Go's grpc client that supports connection reuse.

Pool provides additional features:

• Connection reuse supported by specific MaxConcurrentStreams param.
• Failure reconnection supported by grpc's keepalive.

Getting started

Install

Import package:

import (
    "github.com/shimingyah/pool"
)

go get github.com/shimingyah/pool

Usage

p, err := pool.New("127.0.0.1:8080", pool.DefaultOptions)
if err != nil {
    log.Fatalf("failed to new pool: %v", err)
}
defer p.Close()

conn, err := p.Get()
if err != nil {
    log.Fatalf("failed to get conn: %v", err)
}
defer conn.Close()

// cc := conn.Value()
// client := pb.NewClient(conn.Value())

See the complete example: https://github.com/shimingyah/pool/tree/master/example

Reference

• https://github.com/fatih/pool
• https://github.com/silenceper/pool

License

Pool is under the Apache 2.0 license. See the LICENSE file for details.

Documentation

Index

• Constants
• Variables
• func Dial(address string) (*grpc.ClientConn, error)
• func DialTest(address string) (*grpc.ClientConn, error)
• type Conn
• type Options
  • func CustomOptions(opts ...grpc.DialOption) Options
• type Pool
  • func New(address string, option Options) (Pool, error)

Constants

const (
	// DialTimeout the timeout of create connection
	DialTimeout = 5 * time.Second

	// BackoffMaxDelay provided maximum delay when backing off after failed connection attempts.
	BackoffMaxDelay = 3 * time.Second

	// KeepAliveTime is the duration of time after which if the client doesn't see
	// any activity it pings the server to see if the transport is still alive.
	KeepAliveTime = time.Duration(10) * time.Second

	// KeepAliveTimeout is the duration of time for which the client waits after having
	// pinged for keepalive check and if no activity is seen even after that the connection
	// is closed.
	KeepAliveTimeout = time.Duration(3) * time.Second

	// InitialWindowSize we set it 1GB is to provide system's throughput.
	InitialWindowSize = 1 << 30

	// InitialConnWindowSize we set it 1GB is to provide system's throughput.
	InitialConnWindowSize = 1 << 30

	// MaxSendMsgSize set max gRPC request message size sent to server.
	// If any request message size is larger than current value, an error will be reported from gRPC.
	MaxSendMsgSize = 4 << 30

	// MaxRecvMsgSize set max gRPC receive message size received from server.
	// If any message size is larger than current value, an error will be reported from gRPC.
	MaxRecvMsgSize = 4 << 30
)

Variables

var DefaultOptions = Options{
	Dial:                 Dial,
	MaxIdle:              8,
	MaxActive:            64,
	MaxConcurrentStreams: 64,
	Reuse:                true,
}

DefaultOptions sets a list of recommended options for good performance. Feel free to modify these to suit your needs.

var ErrClosed = errors.New("pool is closed")

ErrClosed is the error resulting if the pool is closed via pool.Close().

Functions

func Dial

func Dial(address string) (*grpc.ClientConn, error)

Dial return a grpc connection with defined configurations.

func DialTest

func DialTest(address string) (*grpc.ClientConn, error)

DialTest return a simple grpc connection with defined configurations.

Types

type Conn

type Conn interface {
	// Value return the actual grpc connection type *grpc.ClientConn.
	Value() *grpc.ClientConn

	// Close decrease the reference of grpc connection, instead of close it.
	// if the pool is full, just close it.
	Close() error
}

Conn single grpc connection inerface

type Options

type Options struct {
	// Dial is an application supplied function for creating and configuring a connection.
	Dial func(address string) (*grpc.ClientConn, 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

	// MaxConcurrentStreams limit on the number of concurrent streams to each single connection
	MaxConcurrentStreams int

	// If Reuse is true and the pool is at the MaxActive limit, then Get() reuse
	// the connection to return, If Reuse is false and the pool is at the MaxActive limit,
	// create a one-time connection to return.
	Reuse bool
}

Options are params for creating grpc connect pool.

func CustomOptions

func CustomOptions(opts ...grpc.DialOption) Options

type Pool

type Pool interface {
	// Get returns a new connection from the pool. Closing the connections puts
	// it back to the Pool. Closing it when the pool is destroyed or full will
	// be counted as an error. we guarantee the conn.Value() isn't nil when conn isn't nil.
	Get() (Conn, error)

	// Close closes the pool and all its connections. After Close() the pool is
	// no longer usable. You can't make concurrent calls Close and Get method.
	// It will be cause panic.
	Close() error

	// Status returns the current status of the pool.
	Status() string
}

Pool interface describes a pool implementation. An ideal pool is threadsafe and easy to use.

func New

func New(address string, option Options) (Pool, error)

New return a connection pool.