gossdb

README

gossdb

English Readme

功能列表

• 参考官方驱动开发，增加连接池支持，改进协议实现方式，提高了数据吞吐量
• 支持 set 相关函数
• 支持 zset 相关函数
• 支持 hset 相关函数
• 支持 queue 相关函数
• 支持 multi 相关函数
• 支持返回值类型转换，可以方便的把从ssdb中取到的内容转化为指定类型
• 支持对象json的序列化，只需要开启Encoding选项
• 支持连接自动回收，支持无错误获取连接，代码调用更简便

2.0主要改进

• 修改所有函数名字，使其符合golang编码规范，通过 golint 验证
• 改进协议实现方式，提高解析效率
• 改进连接池方式，提高连接池的存取效率。连接池由原来的单一连接池，改为块状池，每个块都是一个独立的连接池，多个连接池协作，减少锁的竞争时间
• 支持连接自动回收，支持无错误获取连接，代码调用更简便。原来使用连接必须判断连接是否获取成功，并手工关闭，现在可以省略掉这部分重复代码，使得您更专注于业务逻辑
• 解决高并发时的内存泄漏问题，主要是通过回收计时器和重用连接来解决

性能测试，仅作参考，并不实际操作ssdb，只打开连接然后立即回收

• BenchmarkConnectors_NewClient10-4 5000000 244 ns/op
• BenchmarkConnectors_NewClient100-4 5000000 215 ns/op
• BenchmarkConnectors_NewClient1000-4 5000000 281 ns/op
• BenchmarkConnectors_NewClient5000-4 5000000 282 ns/op

主要配置项

• Host string //ssdb的ip或主机名
• Port int //ssdb的端口
• GetClientTimeout int //获取连接超时时间，单位为秒。默认值: 5
• ReadWriteTimeout int //连接读写超时时间，单位为秒。默认值: 60
• WriteTimeout int //连接写超时时间，单位为秒，如果不设置与ReadWriteTimeout会保持一致。默认值: 0
• ReadTimeout int //连接读超时时间，单位为秒，如果不设置与ReadWriteTimeout会保持一致。默认值: 0
• MaxPoolSize int //最大连接个数。默认值: 100，PoolSize的整数倍，不足的话自动补足。
• MinPoolSize int //最小连接个数。默认值: 20，PoolSize的整数倍，不足的话自动补足。
• PoolSize int //连接池块的连接数。默认值: 20，连接池扩展和收缩时，以此值步进，可根据机器性能调整。
• MaxWaitSize int //最大等待数目，当连接池满后，新建连接将等待池中连接释放后才可以继续，本值限制最大等待的数量，超过本值后将抛出异常。默认值: 1000
• HealthSecond int //连接池内缓存的连接状态检查时间隔，单位为秒。默认值: 30
• Password string //连接的密钥
• WriteBufferSize int //连接写缓冲，默认为8k，单位为kb
• ReadBufferSize int //连接读缓冲，默认为8k，单位为kb
• RetryEnabled bool //是否启用重试，设置为true时，如果请求失败会再重试一次。默认值: false
• ConnectTimeout int //创建连接的超时时间，单位为秒。默认值: 5
• AutoClose bool //是否自动回收连接，如果开启后，获取的连接在使用后立即会被回收，所以不要重复使用。
• Encoding bool //是否开启自动序列化

更多说明请见这里

所有的API基于ssdb的原始API用法，只针对go的特点增加部分方法。所以也可以参照官方文档使用。

示例1：使用自动关闭

//打开连接池，使用默认配置,Host=127.0.0.1,Port=8888,AutoClose=true
if err := gossdb.Start(); err != nil {
	panic(err)
}
//别忘了结束时关闭连接池，当然如果你没有关闭，ssdb也会因错误中断连接的
defer gossdb.Shutdown()
//使用连接，因为AutoClose为true，所以我们没有手工关闭连接
//gossdb.Client()为无错误获取连接方式，所以可以在获取连接后直接调用其它操作函数，如果获取连接出错或是调用函数出错，都会返回err
//这时里要注意gossdb.Client()后要立即接调用的函数，这个函数执行完后ssdb的连接会被回收，所以不要重复使用。
if v, err := gossdb.Client().Get("a"); err == nil {
	println(v.String())
} else {
	println(err.Error())
}

调用起来是不是简单很多^_^

示例2： 不使用自动关闭，适用于一个连接进行多个请求的方式

//使用配置文件，没有将AutoClose设置为true
err := gossdb.Start(&conf.Config{
	Host: "127.0.0.1",
	Port: 8888,
})
if err != nil {
	panic(err)
}
defer gossdb.Shutdown()
c, err := gossdb.NewClient()
if err != nil {
	panic(err)
}
defer c.Close()
if v, err := c.Get("a"); err == nil {
	println(v.String())
} else {
	println(err.Error())
}
if v, err := c.Get("b"); err == nil {
	println(v.String())
} else {
	println(err.Error())
}

Documentation

Overview

Package gossdb the client, derived from the official client, supports connection pooling and USES the same conventions as most clients.

   refer to official driver development, add connection pool support, improve protocol implementation, and improve data throughput
   support for set dependent functions
   supports zset correlation functions
   supports hset correlation functions
   supports queue related functions
   supports multi correlation functions
   supports return value type conversion, which makes it easy to convert content from SSDB to the specified type
   supports serialization of json objects, just open the gossdb.encoding option
   support automatic connection recovery, support error free connection acquisition, code call is easier

Major improvements in 2.0

   modify the names of all functions to make them conform to the golang coding program and pass the golint verification
   improve protocol implementation to improve parsing efficiency
   improve connection pool mode to improve access efficiency of connection pool. Instead of a single connection pool, the connection pool is a block pool,
   each block is a separate connection pool, and multiple connection pools collaborate to reduce lock contention time
   support automatic connection recovery, support error free connection acquisition, code call is easier. Instead of having to determine if the connection
   was successful and close it manually, you can omit this duplicated code and focus on the business logic
   the memory leak problem with high concurrency is solved primarily by recycling timers and reusing connections

The main configuration item

   // SSDB IP or host name
   the Host string
   // SSDB port
   the Port int
   // gets the connection timeout in seconds. Default: 5
   GetClientTimeout int
   // connection read/write timeout in seconds. Default: 60
   ReadWriteTimeout int
   // the connection write timeout, in seconds, is the same as the ReadWriteTimeout if not set. Default: 0
   WriteTimeout int
   // the connection read timeout, in seconds, is the same as the ReadWriteTimeout if not set. Default: 0
   ReadTimeout int
   // maximum number of connections. Default value: 100, integer multiple of PoolSize, if not enough, it will be filled automatically.
   MaxPoolSize int
   // minimum number of connections. Default value: 20, integer multiple of PoolSize.
   MinPoolSize int
   // the number of connections to the pool block. Default value: 20, when connection pool is expanded and contracted, step by this value, which can be adjusted according to machine performance.
   PoolSize int
   // the maximum number of waits. When the connection pool is full, the new connection will wait for the connection in the pool to be released before //    ontinuing. This value limits the maximum number of waits. Default: 1000
   MaxWaitSize int
   // the connection status check interval for the cache in the connection pool is in seconds. Default: 30
   HealthSecond int
   // key for connection
   the Password string
   // connection write buffer, default 8k, in KB
   WriteBufferSize int
   // connection read buffer, default 8k, in KB
   ReadBufferSize int
   // if retry is enabled, set to true and try again if the request fails. Default: false
   RetryEnabled bool
   // the timeout for creating a connection in seconds. Default: 5
   ConnectTimeout int
   // auto close
   AutoClose bool

More instructions please see [here] (https://gowalker.org/github.com/seefan/gossdb)

All apis are essentially faithful to the original API usage of SSDB, with only a few methods added for go features. So you can also refer to the official //  documentation.

Example 1: use automatic shutdown

    //open the connection pool, using the default configuration,Host=127.0.0.1,Port=8888,AutoClose=true
	if err := gossdb.Start(); err != nil {
		panic(err)
	}
	//don't forget to close the connection pool at the end of the session. Of course, if you don't close the connection, the SSDB will also break the //  connection due to an error
	defer gossdb.Shutdown()
	//use the connection, since AutoClose is true, we did not close the connection manually
	//gossdb.client () is error-free connection mode, so it can directly call other operation functions after obtaining the connection. If the connection //  is wrong or the calling function is wrong, it will return err
	if v, err := gossdb.Client().Get("a"); err == nil {
		println(v.String())
	} else {
		println(err.Error())
	}

Call up is many simple  ^_^

Example 2: does not use automatic shutdown, works for a way to connect multiple requests at once

	// with the configuration file, AutoClose is not set to true
    err := gossdb.Start(&conf.Config{
		Host: "127.0.0.1",
		Port: 8888,
	})
	if err != nil {
		panic(err)
	}
	defer gossdb.Shutdown()
	c, err := gossdb.NewClient()
	if err != nil {
		panic(err)
	}
	defer c.Close()
	if v, err := c.Get("a"); err == nil {
		println(v.String())
	} else {
		println(err.Error())
	}
    if v, err := c.Get("b"); err == nil {
		println(v.String())
	} else {
		println(err.Error())
	}

Index

• func Client() *pool.Client
• func NewClient() (*pool.Client, error)
• func NewPool(conf *conf.Config) (*pool.Connectors, error)
• func Shutdown()
• func Start(cfg ...*conf.Config) (err error)

Examples

• Client (AutoClose)
• NewClient (NotAutoClose)

Functions

func Client

func Client() *pool.Client

Client returns a connection If no connection is available in the connection pool, gossdb creates a temporary connection and returns it, and any action on the connection returns an error. This error is used to indicate that the connection pool cannot provide a new connection.

@return PoolClient

这个函数返回一个连接，并且总是成功返回。如果连接池没有可用的连接时，gossdb会创建一个临时的连接并返回， 这个连接进行任何操作都会返回一个错误。这个错误用来标记连接池无法提供新连接。

Example (AutoClose)

Client 注意默认配置里连接自动关闭为true，所以此处没有手工关闭连接。 本地ssdb连接示例。假设host为127.0.0.1，端口为8888

package main

import (
	"github.com/seefan/gossdb"
)

func main() {
	if err := gossdb.Start(); err != nil {
		panic(err)
	}
	defer gossdb.Shutdown()
	if v, err := gossdb.Client().Get("a"); err == nil {
		println(v.String())
	} else {
		println(err.Error())
	}
}

func NewClient

func NewClient() (*pool.Client, error)

NewClient returns a cached connection and possible errors

@return *PoolClient
@return error

这个函数返回一个缓存的连接和一个可能的错误，如果成功返回的错误就为nil。

Example (NotAutoClose)

NewClient 注意默认配置里没有把连接自动关闭为true，所以此处手工关闭连接。 本地ssdb连接示例。假设host为127.0.0.1，端口为8888

package main

import (
	"github.com/seefan/gossdb"
	"github.com/seefan/gossdb/conf"
)

func main() {
	err := gossdb.Start(&conf.Config{
		Host: "127.0.0.1",
		Port: 8888,
	})
	if err != nil {
		panic(err)
	}
	defer gossdb.Shutdown()
	c, err := gossdb.NewClient()
	if err != nil {
		panic(err)
	}
	defer c.Close()
	if v, err := c.Get("a"); err == nil {
		println(v.String())
	} else {
		println(err.Error())
	}
}

func NewPool

func NewPool(conf *conf.Config) (*pool.Connectors, error)

NewPool start a gossdb pool with the initial parameters.

@param conf initial parameters
@return gossdb pool
@return error that may occur on startup. Return nil if successful startup

通常使用NewPool启动连接池，初始化参数由外部传入。如果启动成功返回一个连接池和nil，如果失败返回nil和发生的错误。

func Shutdown

func Shutdown()

Shutdown shutdown gossdb pool

关闭连接池。如果你用Start函数启动了连接池，就用这个函数关闭它。

func Start

func Start(cfg ...*conf.Config) (err error)

Start start a global connection pool. This function can only be started once in the program's lifetime. The Shutdown() is called to close the connection pool when the program ends.

@param cfg initial parameters,optional. Use with default parameters if not specified
@return error that may occur on startup. Return nil if successful startup

启动一个全局的连接池，此函数在程序的生命周期内只能启动一次，程序结束时调用Shutdown函数关闭连接池。 参数cfg是可选的，如果没有指定，会使用默认参数连接ssdb，host为127.0.0.1，port为8888,autoclose为true。一般在学习gossdb时用于本地练习。