client

README

metapipe-memcached

A small and performant concurrent memcached client for golang. It uses protocol pipelining to handle heavy traffic efficiently. It is safe to be used by multiple concurrent goroutines at the same time.

At the moment, it only supports the latest meta protocol, but adding classic text protocol should be possible.

Docs at https://pkg.go.dev/github.com/jsp-lqk/metapipe-memcached

Example

Install and import:

$ go get github.com/jsp-lqk/metapipe-memcached

import "github.com/jsp-lqk/metapipe-memcached"

Create a client:

c, err := client.DefaultClient("127.0.0.1:11211")

Get and set:

mr, err := c.Set("key", []byte("value"), 0)
if err != nil {
// handle
}
gr, err = c.Get("key")
if err != nil {
// handle
}

If you want to customize connection settings, then instead of DefaultClient, use either SingleTargetClient (for a single server connection), or ShardedClient (for multiple servers). Both take either a single or an array of ConnectionTarget, where you can set custom maximum outstanding requests (the amount of requests waiting for response from memcached, default 1000) or the request timeout (in ms, default 1000).

TODO

• backoff retry
• TLS
• tagged routing
• replicated routing (no sharding)
• operation blacklisting
• benchmarking
• monitoring and metrics
• CAS
• classic text protocol
• generics client that takes serializer/deserializer

Documentation

Index

• Variables
• type BaseTCPClient
  • func NewBaseTCPClient(c ConnectionTarget) (*BaseTCPClient, error)
  • func (tc *BaseTCPClient) Dispatch(r []byte) <-chan Response
  • func (tc *BaseTCPClient) Shutdown()
• type Client
  • func DefaultClient(servers ...string) (Client, error)
  • func ShardedClient(targets ...ConnectionTarget) (Client, error)
  • func SingleTargetClient(target ConnectionTarget) (Client, error)
  • func (c *Client) Add(key string, value []byte, ttl int) (MutationResult, error)
  • func (c *Client) Delete(key string) (MutationResult, error)
  • func (c *Client) Get(key string) ([]byte, error)
  • func (c *Client) GetMany(keys []string) (map[string][]byte, error)
  • func (c *Client) Info(key string) (EntryInfo, error)
  • func (c *Client) Replace(key string, value []byte, ttl int) (MutationResult, error)
  • func (c *Client) Set(key string, value []byte, ttl int) (MutationResult, error)
  • func (c *Client) Shutdown()
  • func (c *Client) Touch(key string, ttl int) (MutationResult, error)
• type ConnectionTarget
• type DirectRouter
  • func (r *DirectRouter) Route(key string) MemcacheClient
  • func (r *DirectRouter) Shutdown()
• type EntryInfo
• type InnerMetaClient
  • func NewInnerMetaClient(target ConnectionTarget) (*InnerMetaClient, error)
  • func (c *InnerMetaClient) Add(key string, value []byte, ttl int) (MutationResult, error)
  • func (c *InnerMetaClient) Delete(key string) (MutationResult, error)
  • func (c *InnerMetaClient) Get(key string) ([]byte, error)
  • func (c *InnerMetaClient) GetMany(keys []string) (map[string][]byte, error)
  • func (c *InnerMetaClient) Info(key string) (EntryInfo, error)
  • func (c *InnerMetaClient) Replace(key string, value []byte, ttl int) (MutationResult, error)
  • func (c *InnerMetaClient) Set(key string, value []byte, ttl int) (MutationResult, error)
  • func (c *InnerMetaClient) Shutdown()
  • func (c *InnerMetaClient) Touch(key string, ttl int) (MutationResult, error)
• type MemcacheClient
• type MutationResult
• type Request
• type Response
• type Router
• type ShardedRouter
  • func (r *ShardedRouter) Route(key string) MemcacheClient
  • func (r *ShardedRouter) Shutdown()

Variables

var ErrConnectionOverloaded = errors.New("connection overloaded")

var ErrRequestTimeout = errors.New("request timeout")

Types

type BaseTCPClient

type BaseTCPClient struct {
	ConnectionTarget
	// contains filtered or unexported fields
}

func NewBaseTCPClient

func NewBaseTCPClient(c ConnectionTarget) (*BaseTCPClient, error)

func (*BaseTCPClient) Dispatch

func (tc *BaseTCPClient) Dispatch(r []byte) <-chan Response

func (*BaseTCPClient) Shutdown

func (tc *BaseTCPClient) Shutdown()

type Client

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

A Client is an instance of the metapipe client You should be using only this

func DefaultClient

func DefaultClient(servers ...string) (Client, error)

Creates a default Client, server strings in the format host:ip

func ShardedClient

func ShardedClient(targets ...ConnectionTarget) (Client, error)

Creates a Client that connects to many memcached servers

func SingleTargetClient

func SingleTargetClient(target ConnectionTarget) (Client, error)

Creates a Client that connects to a single memcached server

func (*Client) Add

func (c *Client) Add(key string, value []byte, ttl int) (MutationResult, error)

Stores an entry ONLY if the key does NOT exist in the server

func (*Client) Delete

func (c *Client) Delete(key string) (MutationResult, error)

Deletes an entry

func (*Client) Get

func (c *Client) Get(key string) ([]byte, error)

Gets the contents of an entry

func (*Client) GetMany

func (c *Client) GetMany(keys []string) (map[string][]byte, error)

Gets many entries This method ignores errors, and turn them into the equivalent of cache misses

func (*Client) Info

func (c *Client) Info(key string) (EntryInfo, error)

Gets the information about an entry

func (*Client) Replace

func (c *Client) Replace(key string, value []byte, ttl int) (MutationResult, error)

Stores an entry ONLY if the key DOES exist in the server

func (*Client) Set

func (c *Client) Set(key string, value []byte, ttl int) (MutationResult, error)

Stores an entry

func (*Client) Shutdown

func (c *Client) Shutdown()

Shuts down the client that won't accept or return requests anymore

func (*Client) Touch

func (c *Client) Touch(key string, ttl int) (MutationResult, error)

Updates the time to live of an entry

type ConnectionTarget

type ConnectionTarget struct {
	Address                string
	Port                   int
	MaxOutstandingRequests int
	TimeoutMs              int
}

ConnectionTarget is the information used to locate and connect to a memcached server

type DirectRouter

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

func (*DirectRouter) Route

func (r *DirectRouter) Route(key string) MemcacheClient

func (*DirectRouter) Shutdown

func (r *DirectRouter) Shutdown()

type EntryInfo

type EntryInfo struct {
	TimeToLive  int
	LastAccess  int
	CasId       int
	Fetched     bool
	SlabClassId int
	Size        int
}

EntryInfo contains information about a cache entry

type InnerMetaClient

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

InnerMetaClient implements the memcached meta protocol

func NewInnerMetaClient

func NewInnerMetaClient(target ConnectionTarget) (*InnerMetaClient, error)

func (*InnerMetaClient) Add

func (c *InnerMetaClient) Add(key string, value []byte, ttl int) (MutationResult, error)

func (*InnerMetaClient) Delete

func (c *InnerMetaClient) Delete(key string) (MutationResult, error)

func (*InnerMetaClient) Get

func (c *InnerMetaClient) Get(key string) ([]byte, error)

func (*InnerMetaClient) GetMany

func (c *InnerMetaClient) GetMany(keys []string) (map[string][]byte, error)

func (*InnerMetaClient) Info

func (c *InnerMetaClient) Info(key string) (EntryInfo, error)

func (*InnerMetaClient) Replace

func (c *InnerMetaClient) Replace(key string, value []byte, ttl int) (MutationResult, error)

func (*InnerMetaClient) Set

func (c *InnerMetaClient) Set(key string, value []byte, ttl int) (MutationResult, error)

func (*InnerMetaClient) Shutdown

func (c *InnerMetaClient) Shutdown()

func (*InnerMetaClient) Touch

func (c *InnerMetaClient) Touch(key string, ttl int) (MutationResult, error)

type MemcacheClient

type MemcacheClient interface {
	Add(key string, value []byte, ttl int) (MutationResult, error)
	Delete(key string) (MutationResult, error)
	Get(key string) ([]byte, error)
	GetMany(keys []string) (map[string][]byte, error)
	Info(key string) (EntryInfo, error)
	Replace(key string, value []byte, ttl int) (MutationResult, error)
	Set(key string, value []byte, ttl int) (MutationResult, error)
	Touch(key string, ttl int) (MutationResult, error)
	Shutdown()
}

A MemcacheClient is a client implementation that supports memcached operations

type MutationResult

type MutationResult int

MutationResult contains information about the outcome of a mutation operation (anything but get or info)

const (
	Success MutationResult = iota
	Error
	Exists
	NotFound
	NotStored
)

type Request

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

type Response

type Response struct {
	Header []string
	Value  []byte
	Error  error
}

type Router

type Router interface {
	Route(key string) MemcacheClient
	Shutdown()
}

type ShardedRouter

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

func (*ShardedRouter) Route

func (r *ShardedRouter) Route(key string) MemcacheClient

func (*ShardedRouter) Shutdown

func (r *ShardedRouter) Shutdown()