Gomemcache

https://pkg.go.dev/github.com/bradfitz/gomemcache
Admin
Gomemcache is a memcache client library for the Go programming language that provides a client for...
Tokens:2,928
Snippets:46
Trust Score:9.6
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install gomemcache

Source: https://pkg.go.dev/github.com/bradfitz/gomemcache

Use the go get command to install the library.

```bash
$ go get github.com/bradfitz/gomemcache/memcache
```

--------------------------------

### Initialize and use memcache client

Source: https://pkg.go.dev/github.com/bradfitz/gomemcache

Demonstrates connecting to multiple memcached servers and performing basic set and get operations.

```go
import (
    "github.com/bradfitz/gomemcache/memcache"
)

func main() {
     mc := memcache.New("10.0.0.1:11211", "10.0.0.2:11211", "10.0.0.3:11212")
     mc.Set(&memcache.Item{Key: "foo", Value: []byte("my value")})

     it, err := mc.Get("foo")
     ...
}
```

--------------------------------

### func (c *Client) Get

Source: https://pkg.go.dev/github.com/bradfitz/gomemcache/memcache

Retrieves an item from the memcached server by its key.

```APIDOC
## func (c *Client) Get(key string) (item *Item, err error)

### Description
Retrieves the item associated with the provided key from the cache.

### Parameters
- **key** (string) - Required - The key to retrieve.

### Returns
- **item** (*Item) - The retrieved item if found.
- **err** (error) - Returns ErrCacheMiss if the item is not found.
```

--------------------------------

### Get an item

Source: https://pkg.go.dev/github.com/bradfitz/gomemcache/memcache

Retrieves an item by key. Returns ErrCacheMiss if the key is not found.

```go
func (c *Client) Get(key string) (item *Item, err error)
```

--------------------------------

### Get multiple items

Source: https://pkg.go.dev/github.com/bradfitz/gomemcache/memcache

Batch retrieval of items. Returns a map of found items.

```go
func (c *Client) GetMulti(keys []string) (map[string]*Item, error)
```

--------------------------------

### Get and Touch an item

Source: https://pkg.go.dev/github.com/bradfitz/gomemcache/memcache

Retrieves an item and updates its expiration time.

```go
func (c *Client) GetAndTouch(key string, expiration int32) (item *Item, err error)
```

--------------------------------

### Perform Compare-and-Swap

Source: https://pkg.go.dev/github.com/bradfitz/gomemcache/memcache

Updates an item only if it has not been modified since the last Get call. Returns ErrCASConflict or ErrNotStored on failure.

```go
func (c *Client) CompareAndSwap(item *Item) error
```

--------------------------------

### Create a new Client

Source: https://pkg.go.dev/github.com/bradfitz/gomemcache/memcache

Initializes a new client using a specific ServerSelector.

```go
func NewFromSelector(ss ServerSelector) *Client
```

--------------------------------

### Pick a Server

Source: https://pkg.go.dev/github.com/bradfitz/gomemcache/memcache

Selects a server address based on the provided key.

```go
func (ss *ServerList) PickServer(key string) (net.Addr, error)
```

--------------------------------

### Initialize a new Client

Source: https://pkg.go.dev/github.com/bradfitz/gomemcache/memcache

Creates a new memcache client instance for the specified server addresses.

```go
func New(server ...string) *Client
```

--------------------------------

### View documentation via godoc

Source: https://pkg.go.dev/github.com/bradfitz/gomemcache

Run the godoc command to view full documentation locally.

```bash
$ godoc github.com/bradfitz/gomemcache/memcache
```

--------------------------------

### Define ServerList Structure

Source: https://pkg.go.dev/github.com/bradfitz/gomemcache/memcache

A simple implementation of ServerSelector. The zero value is ready for use.

```go
type ServerList struct {
	// contains filtered or unexported fields
}
```

--------------------------------

### func New

Source: https://pkg.go.dev/github.com/bradfitz/gomemcache/memcache

Creates a new memcache client instance connected to the specified server addresses.

```APIDOC
## func New(server ...string) *Client

### Description
Returns a memcache client using the provided server(s) with equal weight. If a server is listed multiple times, it gets a proportional amount of weight.

### Parameters
- **server** (...string) - Required - A variadic list of memcached server addresses (e.g., "127.0.0.1:11211").

### Returns
- ***Client** - A pointer to the initialized Client instance.
```

--------------------------------

### func (*ServerList) PickServer

Source: https://pkg.go.dev/github.com/bradfitz/gomemcache/memcache

Selects a server address based on the provided key.

```APIDOC
## func (*ServerList) PickServer

### Description
Returns the server address that a given item should be shared onto.

### Signature
`func (ss *ServerList) PickServer(key string) (net.Addr, error)`
```

--------------------------------

### Iterate Over Servers

Source: https://pkg.go.dev/github.com/bradfitz/gomemcache/memcache

Iterates over each server in the list by executing the provided function.

```go
func (ss *ServerList) Each(f func(net.Addr) error) error
```

--------------------------------

### Ping servers

Source: https://pkg.go.dev/github.com/bradfitz/gomemcache/memcache

Checks if all configured instances are alive.

```go
func (c *Client) Ping() error
```

--------------------------------

### func (*ServerList) Each

Source: https://pkg.go.dev/github.com/bradfitz/gomemcache/memcache

Iterates over each server in the ServerList, executing the provided function for each server address.

```APIDOC
## func (*ServerList) Each

### Description
Iterates over each server calling the given function.

### Signature
`func (ss *ServerList) Each(f func(net.Addr) error) error`
```

--------------------------------

### Update Server List

Source: https://pkg.go.dev/github.com/bradfitz/gomemcache/memcache

Updates the list of servers at runtime. This operation is safe for concurrent use.

```go
func (ss *ServerList) SetServers(servers ...string) error
```

--------------------------------

### Prepend to an existing item

Source: https://pkg.go.dev/github.com/bradfitz/gomemcache/memcache

Prepends data to an existing item. Returns ErrNotStored if the key does not exist.

```go
func (c *Client) Prepend(item *Item) error
```

--------------------------------

### Define memcache constants

Source: https://pkg.go.dev/github.com/bradfitz/gomemcache/memcache

Default configuration values for socket timeouts and idle connection limits.

```go
const (
	// DefaultTimeout is the default socket read/write timeout.
	DefaultTimeout = 500 * time.Millisecond

	// DefaultMaxIdleConns is the default maximum number of idle connections
	// kept for any single address.
	DefaultMaxIdleConns = 2
)
```

--------------------------------

### Set an item

Source: https://pkg.go.dev/github.com/bradfitz/gomemcache/memcache

Writes an item to the cache unconditionally.

```go
func (c *Client) Set(item *Item) error
```

--------------------------------

### func (*ServerList) SetServers

Source: https://pkg.go.dev/github.com/bradfitz/gomemcache/memcache

Updates the list of memcached servers at runtime.

```APIDOC
## func (*ServerList) SetServers

### Description
Changes a ServerList's set of servers at runtime and is safe for concurrent use by multiple goroutines. Each server is given equal weight, and a server is given more weight if it's listed multiple times.

### Signature
`func (ss *ServerList) SetServers(servers ...string) error`
```

--------------------------------

### Add an item to cache

Source: https://pkg.go.dev/github.com/bradfitz/gomemcache/memcache

Writes an item only if the key does not already exist. Returns ErrNotStored if the key exists.

```go
func (c *Client) Add(item *Item) error
```

--------------------------------

### Flush all items

Source: https://pkg.go.dev/github.com/bradfitz/gomemcache/memcache

Flushes all items from the cache.

```go
func (c *Client) FlushAll() error
```

--------------------------------

### Replace an item

Source: https://pkg.go.dev/github.com/bradfitz/gomemcache/memcache

Writes an item only if the key already exists.

```go
func (c *Client) Replace(item *Item) error
```

--------------------------------

### Define ServerSelector Interface

Source: https://pkg.go.dev/github.com/bradfitz/gomemcache/memcache

Interface for selecting a memcache server based on an item key. Implementations must be safe for concurrent use.

```go
type ServerSelector interface {
	// PickServer returns the server address that a given item
	// should be shared onto.
	PickServer(key string) (net.Addr, error)
	Each(func(net.Addr) error) error
}
```

--------------------------------

### func (c *Client) Set

Source: https://pkg.go.dev/github.com/bradfitz/gomemcache/memcache

Stores an item in the memcached server.

```APIDOC
## func (c *Client) Set(item *Item) error

### Description
Sets the value of an item in the cache. If the item already exists, it will be overwritten.

### Parameters
- **item** (*Item) - Required - The item to store in the cache.
```

--------------------------------

### Delete all items

Source: https://pkg.go.dev/github.com/bradfitz/gomemcache/memcache

Clears all items from the cache.

```go
func (c *Client) DeleteAll() error
```

--------------------------------

### Define Client struct

Source: https://pkg.go.dev/github.com/bradfitz/gomemcache/memcache

The Client struct manages connections to memcached servers and is safe for concurrent use.

```go
type Client struct {
	// DialContext connects to the address on the named network using the
	// provided context.
	//
	// To connect to servers using TLS (memcached running with "--enable-ssl"),
	// use a DialContext func that uses tls.Dialer.DialContext. See this
	// package's tests as an example.
	DialContext func(ctx context.Context, network, address string) (net.Conn, error)

	// Timeout specifies the socket read/write timeout.
	// If zero, DefaultTimeout is used.
	Timeout time.Duration

	// MaxIdleConns specifies the maximum number of idle connections that will
	// be maintained per address. If less than one, DefaultMaxIdleConns will be
	// used.
	//
	// Consider your expected traffic rates and latency carefully. This should
	// be set to a number higher than your peak parallel requests.
	MaxIdleConns int
	// contains filtered or unexported fields
}
```

--------------------------------

### Touch an item

Source: https://pkg.go.dev/github.com/bradfitz/gomemcache/memcache

Updates the expiration time for a given key.

```go
func (c *Client) Touch(key string, seconds int32) (err error)
```

--------------------------------

### Append to an existing item

Source: https://pkg.go.dev/github.com/bradfitz/gomemcache/memcache

Appends data to an existing item. Returns ErrNotStored if the key does not exist.

```go
func (c *Client) Append(item *Item) error
```

--------------------------------

### Define Memcache Item Structure

Source: https://pkg.go.dev/github.com/bradfitz/gomemcache/memcache

Represents an item to be stored or retrieved from a memcached server.

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

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

	// 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

	// CasID is the compare and swap ID.
	//
	// It's populated by get requests and then the same value is
	// required for a CompareAndSwap request to succeed.
	CasID uint64
}
```

--------------------------------

### Close client connections

Source: https://pkg.go.dev/github.com/bradfitz/gomemcache/memcache

Closes all open connections. The client remains usable after this call.

```go
func (c *Client) Close() error
```

--------------------------------

### Define memcache error variables

Source: https://pkg.go.dev/github.com/bradfitz/gomemcache/memcache

Standard error types returned by the memcache client for various failure scenarios.

```go
var (
	// ErrCacheMiss means that a Get failed because the item wasn't present.
	ErrCacheMiss = errors.New("memcache: cache miss")

	// 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")

	// ErrNotStored means that a conditional write operation (i.e. Add or
	// CompareAndSwap) failed because the condition was not satisfied.
	ErrNotStored = errors.New("memcache: item not stored")

	// ErrServer means that a server error occurred.
	ErrServerError = errors.New("memcache: server error")

	// ErrNoStats means that no statistics were available.
	ErrNoStats = errors.New("memcache: no statistics available")

	// 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("malformed: key is too long or contains invalid characters")

	// ErrNoServers is returned when no servers are configured or available.
	ErrNoServers = errors.New("memcache: no servers configured or available")
)
```

--------------------------------

### func (c *Client) Delete

Source: https://pkg.go.dev/github.com/bradfitz/gomemcache/memcache

Removes an item from the memcached server.

```APIDOC
## func (c *Client) Delete(key string) error

### Description
Deletes the item associated with the provided key from the cache.

### Parameters
- **key** (string) - Required - The key of the item to delete.
```

--------------------------------

### Delete an item

Source: https://pkg.go.dev/github.com/bradfitz/gomemcache/memcache

Removes an item by key. Returns ErrCacheMiss if the item does not exist.

```go
func (c *Client) Delete(key string) error
```

--------------------------------

### ConnectTimeoutError string representation

Source: https://pkg.go.dev/github.com/bradfitz/gomemcache/memcache

Returns the error message for a connection timeout.

```go
func (cte *ConnectTimeoutError) Error() string
```

--------------------------------

### ConnectTimeoutError definition

Source: https://pkg.go.dev/github.com/bradfitz/gomemcache/memcache

Error type used when connection attempts exceed the timeout.

```go
type ConnectTimeoutError struct {
	Addr net.Addr
}
```

--------------------------------

### Increment a value

Source: https://pkg.go.dev/github.com/bradfitz/gomemcache/memcache

Atomically increments a numeric value. Returns ErrCacheMiss if the key does not exist.

```go
func (c *Client) Increment(key string, delta uint64) (newValue uint64, err error)
```

--------------------------------

### Decrement a value

Source: https://pkg.go.dev/github.com/bradfitz/gomemcache/memcache

Atomically decrements a numeric value. Returns ErrCacheMiss if the key does not exist.

```go
func (c *Client) Decrement(key string, delta uint64) (newValue uint64, err error)
```
Tokens:
Raw