gomemcached

package module
v0.0.0-...-33d329a Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Mar 9, 2020 License: MIT Imports: 18 Imported by: 0

README

English/中文

gomemcached

gomemcached定义为轻量级和高性能的memcached Go客户端,特点:

  • 支持二进制协议
  • 支持同步与异步模式(异步模式在v2分支中实现)
  • 易于使用的接口

安装

go get github.com/shaoyuan1943/gomemcached

如何使用

func main() {
    m := gomemcached.NewMemcachedClient([]string{"192.168.2.169:11211", []string{"192.168.2.169:112120"}})
    cas, err := m.Set("First", "HelloWorld", 0, 0)
    if err != nil {
        fmt.Printf("Set err: %v\n", err)
        return
    }

    var value string
    cas, err = m.Get("First", &value)
    if err != nil {
        fmt.Printf("Get err: %v\n", err)
        return
    }
}

接口说明

gomemcached内部采用msgpack序列化数据,对于MemcachedClient而言,每一次操作都会被msgpack序列化为一个完整的数据包,理论上来说,无法对这个数据包增加或减少部分数据。当需要对数据进行增加或减少部分数据的操作时,请使用*RawData函数,此类函数不使用msgpack序列化value。

参数

type KeyArgs struct {
	Key        string   
	Value      interface{}
	Expiration uint32   // 过期时间,以秒为单位
	CAS        uint64   // 修订号,当cas不为0时:所请求的操作务必仅在key存在且CAS值与提供的值相同时成功
	Delta      uint64   // 原子操作时得步长值
}

接口

AddServer(addr string, maxConnPerServer uint32) error
添加一个memcached server,操作成功时返回值为nil 。

SetServerErrorCallback(call ServerErrorCallback)
设置某个memcached server失效时的回调函数,该回调函数的参数是失效server的地址。

Exit()
结束该client,理论上来说,此函数调用后该client将无法使用。

Get(key string, value interface{}) (uint64, error)
获取key的值,value是值变量的指针。返回值是key对应的CAS,操作成功时error为nil。

Set(args *KeyArgs) (uint64, error)
设置key的值,返回值是key对应的CAS,操作成功时error为nil。

SetRawData(args *KeyArgs) (uint64, error)
该函数行为与Set一致,当value需要Append或Prepend时,使用该函数完成操作。返回值是key对应的CAS,操作成功时error为nil。此函数不会序列化数据。

Add(args *KeyArgs) (uint64, error)
添加某个值,返回值是key对应的CAS,操作成功时error为nil。

AddRawData(args *KeyArgs) (uint64, error)
该函数行为与Add一致,当value需要Append或Prepend时,需要使用该函数完成操作。返回值是key对应的CAS,操作成功时error为nil。此函数不会序列化数据。

Replace(args *KeyArgs) (uint64, error)
替换key的值。返回值是key对应的CAS,操作成功时error为nil。

ReplaceRawData(args *KeyArgs) (uint64, error)
该函数行为与Add一致,当value需要Append或Prepend时,需要使用该函数完成add操作。返回值是key对应的CAS,操作成功时error为nil。此函数不会序列化数据。

Append(args *KeyArgs) (uint64, error)
Prepend(args *KeyArgs) (uint64, error)

向一个已存在的值的尾部/首部添加数据,返回值是key对应的CAS,操作成功时error为nil。此函数不会序列化数据。

Increment(args *KeyArgs) (uint64, uint64, error)
Decrement(args *KeyArgs) (uint64, uint64, error)
原子操作,已存在的值增加/减少delta,如key不存在则该操作为返回key的初始值,操作成功时error为nil。

TouchAtomicValue(key string) (uint64, error)
返回某个原子的当前值,操作成功时error为nil。

Flush(args *KeyArgs) error
清除所有项,当args.Expiration不为0,则表示延迟多少秒后清除。

更多

https://github.com/memcached/memcached/wiki/BinaryProtocolRevamped

开源协议

MIT License

Documentation

Index

Constants

View Source
const (
	MAGIC_REQUEST  uint8 = 0x80
	MAGIC_RESPONSE uint8 = 0x81
)
View Source
const (
	STATUS_OK                uint16 = 0x0000
	STATUS_KEY_NOT_FOUND     uint16 = 0x0001
	STATUS_KEY_EXISTS        uint16 = 0x0002
	STATUS_VALUE_TOO_LARGE   uint16 = 0x0003
	STATUS_INVALID_ARGS      uint16 = 0x0004
	STATUS_NOT_STORED        uint16 = 0x0005
	STATUS_NON_NUMERIC_VALUE uint16 = 0x0006
	STATUS_VBUCKET_NOT_FOUND uint16 = 0x0007
	STATUS_AUTH_ERROR        uint16 = 0x0008
	STATUS_AUTH_CONTINUE     uint16 = 0x0009
	STATUS_UNKNOWN_COMMAND   uint16 = 0x0081
	STATUS_OUT_OF_MEMORY     uint16 = 0x0082
	STATUS_NOT_SUPPORTED     uint16 = 0x0083
	STATUS_INTERNAL_ERROR    uint16 = 0x0084
	STATUS_BUSY              uint16 = 0x0085
	STATUS_TEMPORARY_FAILURE uint16 = 0x0086
)
View Source
const (
	OPCODE_GET     uint8 = 0x00
	OPCODE_SET     uint8 = 0x01
	OPCODE_ADD     uint8 = 0x02
	OPCODE_REPLACE uint8 = 0x03
	OPCODE_DEL     uint8 = 0x04
	OPCODE_INCR    uint8 = 0x05
	OPCODE_DECR    uint8 = 0x06
	OPCODE_QUIT    uint8 = 0x07
	OPCODE_FLUSH   uint8 = 0x08
	OPCODE_NOOP    uint8 = 0x0a
	OPCODE_VERSION uint8 = 0x0b
	OPCODE_GETK    uint8 = 0x0c
	OPCODE_APPEND  uint8 = 0x0e
	OPCODE_PREPEND uint8 = 0x0f
	OPCODE_STAT    uint8 = 0x10
)
View Source
const (
	REQ_HEADER_LEN int = 24
	RSP_HEADER_LEN int = 24
)
View Source
const (
	RAW_DATA uint8 = 0x00
)
View Source
const (
	USE_MSGP_FLAG uint32 = 0x01
)

Variables

View Source
var (
	NodeRepetitions       = 160
	RingPosition          = 4
	CommanderID     int64 = 10000
)
View Source
var (
	ConnectTimeout = time.Duration(5) * time.Second
	ReadTimeout    = time.Duration(5) * time.Second
	WriterTimeout  = time.Duration(5) * time.Second
)
View Source
var (
	ErrInvalidArguments        = errors.New("Invalid arguments")
	ErrNotConnected            = errors.New("Not connected server")
	ErrConnError               = errors.New("Connection error")
	ErrFillRequestHeaderFailed = errors.New("Fill request header failed")
	ErrNotFoundServerNode      = errors.New("Not found server node")
	ErrNoUsableConnection      = errors.New("No usable connection")
	ErrBadConnection           = errors.New("Bad connection")
	ErrServerAlreadyInCluster  = errors.New("Server already in Cluster")
	// memcached status
	ErrKeyNotFound             = NewStatusError(errors.New("Key not found"))
	ErrKeyExists               = NewStatusError(errors.New("Key exists"))
	ErrValueTooLarge           = NewStatusError(errors.New("Value too large"))
	ErrItemNotStored           = NewStatusError(errors.New("Item not stored"))
	ErrNoNumericValue          = NewStatusError(errors.New("Incr/Decr on non-numeric value"))
	ErrVbucketNotFound         = NewStatusError(errors.New("The vbucket belongs to another server"))
	ErrAuthFailed              = NewStatusError(errors.New("Authentication error"))
	ErrAuthContinue            = NewStatusError(errors.New("Authentication continue"))
	ErrUnknownCommand          = NewStatusError(errors.New("Unknown command"))
	ErrOutOfMemory             = NewStatusError(errors.New("Out of memory"))
	ErrNotSupported            = NewStatusError(errors.New("Not supported"))
	ErrInternalError           = NewStatusError(errors.New("Internal error"))
	ErrBusy                    = NewStatusError(errors.New("Internal error"))
	ErrTemporaryFailure        = NewStatusError(errors.New("Temporary failure"))
	ErrUnmarshalFailed         = NewStatusError(errors.New("Unmarshal value failed"))
	ErrMarshalFailed           = NewStatusError(errors.New("Marshal value failed"))
	ErrCommandArgumentsInvalid = NewStatusError(errors.New("Command arguments invalid"))
	ErrTypeInvalid             = NewStatusError(errors.New("Type invalid"))
)
View Source
var (
	HashCRC32Table = crc32.MakeTable(crc32.IEEE)
)

Functions

func KetamaHash

func KetamaHash(key string, index uint32) []uint32

func MakeHash

func MakeHash(key string) uint32

func WriteUint16

func WriteUint16(buffer *ByteBuffer, value uint16)

func WriteUint32

func WriteUint32(buffer *ByteBuffer, value uint32)

func WriteUint64

func WriteUint64(buffer *ByteBuffer, value uint64)

Types

type Client

type Client interface {
	// Add a memcached server.
	AddServer(addr string, maxConnPerServer uint32) error

	// Set callback when memcached server failed.
	// The callback's parameter is server address.
	SetServerErrorCallback(errCall ServerErrorCallback)

	// Exit client by manual control.
	// In theory that client will not be available after this function is called.
	Exit()

	// Get the value of key.
	// `value` is a pointer to a value variable.
	// Return value is the CAS corresponding to the key,
	// the error is nil when the operation is successful.
	Get(key string, value interface{}) (uint64, error)

	// Set the value of key.
	// Return value is the CAS corresponding to the key,
	// the error is nil when operation is successful.
	Set(args *KeyArgs) (uint64, error)

	// Same as `Set`.
	// When increase or decrease part of the data, must use this function.
	// Return value is CAS,
	// the error is nil when operation is successful, the function does not serialize data.
	SetRawData(args *KeyArgs) (uint64, error)

	// Add the value of key.
	// Return value is CAS, the error is nil when operation is successful.
	Add(args *KeyArgs) (uint64, error)

	// Same as `Add`.
	// When increase or decrease part of the data, must use this function.
	AddRawData(args *KeyArgs) (uint64, error)

	// Replace the value of key.
	// Return value is CAS, the error is nil when operation is successful.
	Replace(args *KeyArgs) (uint64, error)

	// Same as `Replace`
	// When increase or decrease part of the data, must use this function.
	ReplaceRawData(args *KeyArgs) (uint64, error)

	// Appends data to the tail/head of an existing value.
	// Return value is the CAS, and the error is nil when the operation is successful.
	// This function does not serialize data
	Append(args *KeyArgs) (uint64, error)
	Prepend(args *KeyArgs) (uint64, error)

	// Atomic operation, the delta of the existing value is increased/decreased.
	// If the key does not exist, the operation returns the initial value of the key.
	// The error is nil when the operation is successful
	Increment(args *KeyArgs) (uint64, uint64, error)
	Decrement(args *KeyArgs) (uint64, uint64, error)

	// Returns the current value of an atom.
	// The error is nil when the operation is successful
	TouchAtomicValue(key string) (uint64, error)

	// Flush all items,
	// flush the items in the cache now or some time in the future as specified by the expiration field
	Flush(args *KeyArgs) error
}

func NewMemcachedClient

func NewMemcachedClient(addrs []string, maxConnPerServer uint32) Client

type Cluster

type Cluster struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

func (*Cluster) AddServer2Cluster

func (cl *Cluster) AddServer2Cluster(addr string, maxConnPerServer uint32) error

func (*Cluster) ChooseServerCommanderByKey

func (cl *Cluster) ChooseServerCommanderByKey(key string) (*Server, *Commander, error)

func (*Cluster) ChooseServerCommanderByServerAddr

func (cl *Cluster) ChooseServerCommanderByServerAddr(addr string) (*Server, *Commander, error)

func (*Cluster) ReleaseServerCommander

func (cl *Cluster) ReleaseServerCommander(s *Server, cmder *Commander)

type CodecDecoder

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

func (*CodecDecoder) Decode

func (decoder *CodecDecoder) Decode(data []byte, v interface{}) error

type CodecEncoder

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

func (*CodecEncoder) Encode

func (encoder *CodecEncoder) Encode(v interface{}) ([]byte, error)

encoder := GetEncoder() data, err := encoder.Encode(v) PutEncoder(encoder) use data....

Dont do this, must put encoder to pool after data(new slice from encodeBuffer) use completed to avoid data conflict

type Commander

type Commander struct {
	ID int64
	// contains filtered or unexported fields
}

func (*Commander) Giveup

func (cmder *Commander) Giveup()

type Decoder

type Decoder interface {
	Decode(data []byte, v interface{}) error
}

type Encoder

type Encoder interface {
	Encode(v interface{}) ([]byte, error)
}

type KeyArgs

type KeyArgs struct {
	Key        string
	Value      interface{}
	Expiration uint32
	CAS        uint64
	Delta      uint64
	// contains filtered or unexported fields
}

type MemcachedClient

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

func (*MemcachedClient) Add

func (m *MemcachedClient) Add(args *KeyArgs) (uint64, error)

func (*MemcachedClient) AddRawData

func (m *MemcachedClient) AddRawData(args *KeyArgs) (uint64, error)

func (*MemcachedClient) AddServer

func (m *MemcachedClient) AddServer(addr string, maxConnPerServer uint32) error

func (*MemcachedClient) Append

func (m *MemcachedClient) Append(args *KeyArgs) (uint64, error)

func (*MemcachedClient) Decrement

func (m *MemcachedClient) Decrement(args *KeyArgs) (uint64, uint64, error)

func (*MemcachedClient) Exit

func (m *MemcachedClient) Exit()

func (*MemcachedClient) Flush

func (m *MemcachedClient) Flush(args *KeyArgs) error

func (*MemcachedClient) Get

func (m *MemcachedClient) Get(key string, value interface{}) (uint64, error)

func (*MemcachedClient) Increment

func (m *MemcachedClient) Increment(args *KeyArgs) (uint64, uint64, error)

func (*MemcachedClient) Prepend

func (m *MemcachedClient) Prepend(args *KeyArgs) (uint64, error)

func (*MemcachedClient) Replace

func (m *MemcachedClient) Replace(args *KeyArgs) (uint64, error)

func (*MemcachedClient) ReplaceRawData

func (m *MemcachedClient) ReplaceRawData(args *KeyArgs) (uint64, error)

func (*MemcachedClient) Set

func (m *MemcachedClient) Set(args *KeyArgs) (uint64, error)

func (*MemcachedClient) SetRawData

func (m *MemcachedClient) SetRawData(args *KeyArgs) (uint64, error)

func (*MemcachedClient) SetServerErrorCallback

func (m *MemcachedClient) SetServerErrorCallback(errCall ServerErrorCallback)

func (*MemcachedClient) TouchAtomicValue

func (m *MemcachedClient) TouchAtomicValue(key string) (uint64, error)

type RequestHeader

type RequestHeader struct {
	Magic    uint8
	Opcode   uint8
	KeyLen   uint16
	ExtLen   uint8
	DataType uint8
	Status   uint16
	BodyLen  uint32
	Opaque   uint32
	CAS      uint64
}

type Server

type Server struct {
	Addr              string
	VirtualHashs      []uint32
	MaxCommanderCount uint32
	// contains filtered or unexported fields
}

type ServerErrorCallback

type ServerErrorCallback func(addr string)

type SortList

type SortList []uint32

func (SortList) Len

func (s SortList) Len() int

func (SortList) Less

func (s SortList) Less(i, j int) bool

func (SortList) Swap

func (s SortList) Swap(i, j int)

type StatusError

type StatusError struct {
	Err error
}

func NewStatusError

func NewStatusError(err error) *StatusError

func (*StatusError) Error

func (s *StatusError) Error() string

func (*StatusError) Is

func (s *StatusError) Is(err error) bool

func (*StatusError) Unwrap

func (s *StatusError) Unwrap() error

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL