Back to godoc.org

Package memcache

v0.3.3
Latest Go to latest

The latest major version is .

Published: Jan 20, 2020 | License: MIT | Module: github.com/bilibili/kratos

Index

Examples

Constants

const (

	// FlagRAW default flag.
	FlagRAW = uint32(0)
	// FlagGOB gob encoding.
	FlagGOB = uint32(1) << 0
	// FlagJSON json encoding.
	FlagJSON = uint32(1) << 1
	// FlagProtobuf protobuf
	FlagProtobuf = uint32(1) << 2

	// FlagGzip gzip compress.
	FlagGzip = uint32(1) << 15
)

Variables

var (
	// ErrNotFound not found
	ErrNotFound = errors.New("memcache: key not found")
	// ErrExists exists
	ErrExists = errors.New("memcache: key exists")
	// ErrNotStored not stored
	ErrNotStored = errors.New("memcache: key not stored")
	// ErrCASConflict means that a CompareAndSwap call failed due to the
	// cached value being modified between the Get and the CompareAndSwap.
	// If the cached value was simply evicted rather than replaced,
	// ErrNotStored will be returned instead.
	ErrCASConflict = errors.New("memcache: compare-and-swap conflict")

	// ErrPoolExhausted is returned from a pool connection method (Store, Get,
	// Delete, IncrDecr, Err) when the maximum number of database connections
	// in the pool has been reached.
	ErrPoolExhausted = errors.New("memcache: connection pool exhausted")
	// ErrPoolClosed pool closed
	ErrPoolClosed = errors.New("memcache: connection pool closed")
	// ErrConnClosed conn closed
	ErrConnClosed = errors.New("memcache: connection closed")
	// ErrMalformedKey is returned when an invalid key is used.
	// Keys must be at maximum 250 bytes long and not
	// contain whitespace or control characters.
	ErrMalformedKey = errors.New("memcache: malformed key is too long or contains invalid characters")
	// ErrValueSize item value size must less than 1mb
	ErrValueSize = errors.New("memcache: item value size must not greater than 1mb")
	// ErrStat stat error for monitor
	ErrStat = errors.New("memcache unexpected errors")
	// ErrItem item nil.
	ErrItem = errors.New("memcache: item object nil")
	// ErrItemObject object type Assertion failed
	ErrItemObject = errors.New("memcache: item object protobuf type assertion failed")
)

type Config

type Config struct {
	*pool.Config

	Name         string // memcache name, for trace
	Proto        string
	Addr         string
	DialTimeout  xtime.Duration
	ReadTimeout  xtime.Duration
	WriteTimeout xtime.Duration
}

Config memcache config.

type Conn

type Conn interface {
	// Close closes the connection.
	Close() error

	// Err returns a non-nil value if the connection is broken. The returned
	// value is either the first non-nil value returned from the underlying
	// network connection or a protocol parsing error. Applications should
	// close broken connections.
	Err() error

	// Add writes the given item, if no value already exists for its key.
	// ErrNotStored is returned if that condition is not met.
	Add(item *Item) error

	// Set writes the given item, unconditionally.
	Set(item *Item) error

	// Replace writes the given item, but only if the server *does* already
	// hold data for this key.
	Replace(item *Item) error

	// Get sends a command to the server for gets data.
	Get(key string) (*Item, error)

	// GetMulti is a batch version of Get. The returned map from keys to items
	// may have fewer elements than the input slice, due to memcache cache
	// misses. Each key must be at most 250 bytes in length.
	// If no error is returned, the returned map will also be non-nil.
	GetMulti(keys []string) (map[string]*Item, error)

	// Delete deletes the item with the provided key.
	// The error ErrNotFound is returned if the item didn't already exist in
	// the cache.
	Delete(key string) error

	// Increment atomically increments key by delta. The return value is the
	// new value after being incremented or an error. If the value didn't exist
	// in memcached the error is ErrNotFound. The value in memcached must be
	// an decimal number, or an error will be returned.
	// On 64-bit overflow, the new value wraps around.
	Increment(key string, delta uint64) (newValue uint64, err error)

	// Decrement atomically decrements key by delta. The return value is the
	// new value after being decremented or an error. If the value didn't exist
	// in memcached the error is ErrNotFound. The value in memcached must be
	// an decimal number, or an error will be returned. On underflow, the new
	// value is capped at zero and does not wrap around.
	Decrement(key string, delta uint64) (newValue uint64, err error)

	// CompareAndSwap writes the given item that was previously returned by
	// Get, if the value was neither modified or evicted between the Get and
	// the CompareAndSwap calls. The item's Key should not change between calls
	// but all other item fields may differ. ErrCASConflict is returned if the
	// value was modified in between the calls.
	// ErrNotStored is returned if the value was evicted in between the calls.
	CompareAndSwap(item *Item) error

	// Touch updates the expiry for the given key. The seconds parameter is
	// either a Unix timestamp or, if seconds is less than 1 month, the number
	// of seconds into the future at which time the item will expire.
	// ErrNotFound is returned if the key is not in the cache. The key must be
	// at most 250 bytes in length.
	Touch(key string, seconds int32) (err error)

	// Scan converts value read from the memcache into the following
	// common Go types and special types:
	//
	//    *string
	//    *[]byte
	//    *interface{}
	//
	Scan(item *Item, v interface{}) (err error)

	// Add writes the given item, if no value already exists for its key.
	// ErrNotStored is returned if that condition is not met.
	AddContext(ctx context.Context, item *Item) error

	// Set writes the given item, unconditionally.
	SetContext(ctx context.Context, item *Item) error

	// Replace writes the given item, but only if the server *does* already
	// hold data for this key.
	ReplaceContext(ctx context.Context, item *Item) error

	// Get sends a command to the server for gets data.
	GetContext(ctx context.Context, key string) (*Item, error)

	// GetMulti is a batch version of Get. The returned map from keys to items
	// may have fewer elements than the input slice, due to memcache cache
	// misses. Each key must be at most 250 bytes in length.
	// If no error is returned, the returned map will also be non-nil.
	GetMultiContext(ctx context.Context, keys []string) (map[string]*Item, error)

	// Delete deletes the item with the provided key.
	// The error ErrNotFound is returned if the item didn't already exist in
	// the cache.
	DeleteContext(ctx context.Context, key string) error

	// Increment atomically increments key by delta. The return value is the
	// new value after being incremented or an error. If the value didn't exist
	// in memcached the error is ErrNotFound. The value in memcached must be
	// an decimal number, or an error will be returned.
	// On 64-bit overflow, the new value wraps around.
	IncrementContext(ctx context.Context, key string, delta uint64) (newValue uint64, err error)

	// Decrement atomically decrements key by delta. The return value is the
	// new value after being decremented or an error. If the value didn't exist
	// in memcached the error is ErrNotFound. The value in memcached must be
	// an decimal number, or an error will be returned. On underflow, the new
	// value is capped at zero and does not wrap around.
	DecrementContext(ctx context.Context, key string, delta uint64) (newValue uint64, err error)

	// CompareAndSwap writes the given item that was previously returned by
	// Get, if the value was neither modified or evicted between the Get and
	// the CompareAndSwap calls. The item's Key should not change between calls
	// but all other item fields may differ. ErrCASConflict is returned if the
	// value was modified in between the calls.
	// ErrNotStored is returned if the value was evicted in between the calls.
	CompareAndSwapContext(ctx context.Context, item *Item) error

	// Touch updates the expiry for the given key. The seconds parameter is
	// either a Unix timestamp or, if seconds is less than 1 month, the number
	// of seconds into the future at which time the item will expire.
	// ErrNotFound is returned if the key is not in the cache. The key must be
	// at most 250 bytes in length.
	TouchContext(ctx context.Context, key string, seconds int32) (err error)
}

Conn represents a connection to a Memcache server. Command Reference: https://github.com/memcached/memcached/wiki/Commands

Example (Get)

Code:

var (
	err   error
	item2 *Item
	conn  Conn
	p     struct {
		Name string
		Age  int64
	}
)
cnop := DialConnectTimeout(time.Duration(time.Second))
rdop := DialReadTimeout(time.Duration(time.Second))
wrop := DialWriteTimeout(time.Duration(time.Second))
if conn, err = Dial("tcp", testExampleAddr, cnop, rdop, wrop); err != nil {
	fmt.Println(err)
	return
}
if item2, err = conn.Get("test_raw"); err != nil {
	fmt.Println(err)
} else {
	if err = conn.Scan(item2, &p); err != nil {
		fmt.Printf("FlagRAW conn.Scan error(%v)\n", err)
		return
	}
}
// FlagGZip
if item2, err = conn.Get("test_gzip"); err != nil {
	fmt.Println(err)
} else {
	if err = conn.Scan(item2, &p); err != nil {
		fmt.Printf("FlagGZip conn.Scan error(%v)\n", err)
		return
	}
}
// FlagGOB
if item2, err = conn.Get("test_gob"); err != nil {
	fmt.Println(err)
} else {
	if err = conn.Scan(item2, &p); err != nil {
		fmt.Printf("FlagGOB conn.Scan error(%v)\n", err)
		return
	}
}
// FlagJSON
if item2, err = conn.Get("test_json"); err != nil {
	fmt.Println(err)
} else {
	if err = conn.Scan(item2, &p); err != nil {
		fmt.Printf("FlagJSON conn.Scan error(%v)\n", err)
		return
	}
}

Example (GetMulti)

Code:

var (
	err  error
	conn Conn
	res  map[string]*Item
	keys = []string{"test_raw", "test_gzip"}
	p    struct {
		Name string
		Age  int64
	}
)
cnop := DialConnectTimeout(time.Duration(time.Second))
rdop := DialReadTimeout(time.Duration(time.Second))
wrop := DialWriteTimeout(time.Duration(time.Second))
if conn, err = Dial("tcp", testExampleAddr, cnop, rdop, wrop); err != nil {
	fmt.Println(err)
	return
}
if res, err = conn.GetMulti(keys); err != nil {
	fmt.Printf("conn.GetMulti(%v) error(%v)", keys, err)
	return
}
for _, v := range res {
	if err = conn.Scan(v, &p); err != nil {
		fmt.Printf("conn.Scan error(%v)\n", err)
		return
	}
	fmt.Println(p)
}
{golang 10}
{golang 10}
Example (Set)

Code:

var (
	err    error
	value  []byte
	conn   Conn
	expire int32 = 100
	p            = struct {
		Name string
		Age  int64
	}{"golang", 10}
)
cnop := DialConnectTimeout(time.Duration(time.Second))
rdop := DialReadTimeout(time.Duration(time.Second))
wrop := DialWriteTimeout(time.Duration(time.Second))
if value, err = json.Marshal(p); err != nil {
	fmt.Println(err)
	return
}
if conn, err = Dial("tcp", testExampleAddr, cnop, rdop, wrop); err != nil {
	fmt.Println(err)
	return
}
// FlagRAW test
itemRaw := &Item{
	Key:        "test_raw",
	Value:      value,
	Expiration: expire,
}
if err = conn.Set(itemRaw); err != nil {
	fmt.Println(err)
	return
}
// FlagGzip
itemGZip := &Item{
	Key:        "test_gzip",
	Value:      value,
	Flags:      FlagGzip,
	Expiration: expire,
}
if err = conn.Set(itemGZip); err != nil {
	fmt.Println(err)
	return
}
// FlagGOB
itemGOB := &Item{
	Key:        "test_gob",
	Object:     p,
	Flags:      FlagGOB,
	Expiration: expire,
}
if err = conn.Set(itemGOB); err != nil {
	fmt.Println(err)
	return
}
// FlagJSON
itemJSON := &Item{
	Key:        "test_json",
	Object:     p,
	Flags:      FlagJSON,
	Expiration: expire,
}
if err = conn.Set(itemJSON); err != nil {
	fmt.Println(err)
	return
}
// FlagJSON | FlagGzip
itemJSONGzip := &Item{
	Key:        "test_jsonGzip",
	Object:     p,
	Flags:      FlagJSON | FlagGzip,
	Expiration: expire,
}
if err = conn.Set(itemJSONGzip); err != nil {
	fmt.Println(err)
	return
}

func Dial

func Dial(network, address string, options ...DialOption) (Conn, error)

Dial connects to the Memcache server at the given network and address using the specified options.

func MockWith

func MockWith(err error) Conn

MockWith error

type DialOption

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

DialOption specifies an option for dialing a Memcache server.

func DialConnectTimeout

func DialConnectTimeout(d time.Duration) DialOption

DialConnectTimeout specifies the timeout for connecting to the Memcache server.

func DialNetDial

func DialNetDial(dial func(network, addr string) (net.Conn, error)) DialOption

DialNetDial specifies a custom dial function for creating TCP connections. If this option is left out, then net.Dial is used. DialNetDial overrides DialConnectTimeout.

func DialReadTimeout

func DialReadTimeout(d time.Duration) DialOption

DialReadTimeout specifies the timeout for reading a single command reply.

func DialWriteTimeout

func DialWriteTimeout(d time.Duration) DialOption

DialWriteTimeout specifies the timeout for writing a single command.

type Item

type Item struct {
	// Key is the Item's key (250 bytes maximum).
	Key string

	// Value is the Item's value.
	Value []byte

	// Object is the Item's object for use codec.
	Object interface{}

	// Flags are server-opaque flags whose semantics are entirely
	// up to the app.
	Flags uint32

	// Expiration is the cache expiration time, in seconds: either a relative
	// time from now (up to 1 month), or an absolute Unix epoch time.
	// Zero means the Item has no expiration time.
	Expiration int32
	// contains filtered or unexported fields
}

Item is an reply to be got or stored in a memcached server.

func JSONItem

func JSONItem(key string, v interface{}, flags uint32, expiration int32) *Item

JSONItem item with FlagJSON flag.

Expiration is the cache expiration time, in seconds: either a relative time from now (up to 1 month), or an absolute Unix epoch time. Zero means the Item has no expiration time.

func ProtobufItem

func ProtobufItem(key string, message proto.Message, flags uint32, expiration int32) *Item

ProtobufItem item with FlagProtobuf flag.

Expiration is the cache expiration time, in seconds: either a relative time from now (up to 1 month), or an absolute Unix epoch time. Zero means the Item has no expiration time.

func RawItem

func RawItem(key string, data []byte, flags uint32, expiration int32) *Item

RawItem item with FlagRAW flag.

Expiration is the cache expiration time, in seconds: either a relative time from now (up to 1 month), or an absolute Unix epoch time. Zero means the Item has no expiration time.

type Memcache

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

Memcache memcache client

func New

func New(cfg *Config) *Memcache

New get a memcache client

func (*Memcache) Add

func (mc *Memcache) Add(ctx context.Context, item *Item) (err error)

Add writes the given item, if no value already exists for its key. ErrNotStored is returned if that condition is not met.

func (*Memcache) Close

func (mc *Memcache) Close() error

Close close connection pool

func (*Memcache) CompareAndSwap

func (mc *Memcache) CompareAndSwap(ctx context.Context, item *Item) (err error)

CompareAndSwap writes the given item that was previously returned by Get

func (*Memcache) Conn

func (mc *Memcache) Conn(ctx context.Context) Conn

Conn direct get a connection

func (*Memcache) Decrement

func (mc *Memcache) Decrement(ctx context.Context, key string, delta uint64) (newValue uint64, err error)

Decrement atomically decrements key by delta.

func (*Memcache) Delete

func (mc *Memcache) Delete(ctx context.Context, key string) (err error)

Delete deletes the item with the provided key.

func (*Memcache) Get

func (mc *Memcache) Get(ctx context.Context, key string) *Reply

Get sends a command to the server for gets data.

func (*Memcache) GetMulti

func (mc *Memcache) GetMulti(ctx context.Context, keys []string) (*Replies, error)

GetMulti is a batch version of Get

func (*Memcache) Increment

func (mc *Memcache) Increment(ctx context.Context, key string, delta uint64) (newValue uint64, err error)

Increment atomically increments key by delta.

func (*Memcache) Replace

func (mc *Memcache) Replace(ctx context.Context, item *Item) (err error)

Replace writes the given item, but only if the server *does* already hold data for this key.

func (*Memcache) Set

func (mc *Memcache) Set(ctx context.Context, item *Item) (err error)

Set writes the given item, unconditionally.

func (*Memcache) Touch

func (mc *Memcache) Touch(ctx context.Context, key string, timeout int32) (err error)

Touch updates the expiry for the given key.

type Pool

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

Pool memcache connection pool struct. Deprecated: Use Memcache instead

func NewPool

func NewPool(cfg *Config) (p *Pool)

NewPool new a memcache conn pool. Deprecated: Use New instead

func (*Pool) Close

func (p *Pool) Close() error

Close release the resources used by the pool.

func (*Pool) Get

func (p *Pool) Get(ctx context.Context) Conn

Get gets a connection. The application must close the returned connection. This method always returns a valid connection so that applications can defer error handling to the first use of the connection. If there is an error getting an underlying connection, then the connection Err, Do, Send, Flush and Receive methods return that error.

type Replies

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

Replies is the result of GetMulti

func (*Replies) Close

func (rs *Replies) Close() (err error)

Close close rows.

func (*Replies) Item

func (rs *Replies) Item(key string) *Item

Item get Item from rows

func (*Replies) Keys

func (rs *Replies) Keys() (keys []string)

Keys keys of result

func (*Replies) Scan

func (rs *Replies) Scan(key string, v interface{}) (err error)

Scan converts value, read from key in rows

type Reply

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

Reply is the result of Get

func (*Reply) Item

func (r *Reply) Item() *Item

Item get raw Item

func (*Reply) Scan

func (r *Reply) Scan(v interface{}) (err error)

Scan converts value, read from the memcache

Package Files

Documentation was rendered with GOOS=linux and GOARCH=amd64.

Jump to identifier

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to identifier