README
¶
memc
memc is a modern and generics enabled memcached client library for Go.
requires go1.23+
October 2024: (!) This package is very new and may contain bugs and missing features.
Getting Started
The memc package can be added to a Go project with go get.
go get cattlecloud.net/go/memc@latest
import "cattlecloud.net/go/memc"
Examples
client := memc.New(
[]string{"localhost:11211"},
)
err := memc.Set(client, "my/key/name", "some_value")
Note that the memc library can handle arbitrary value types, as long as they
can be encoded using Go's built-in gob package. The library automatically
handles serialization on writes and de-serialization on reads.
err := memc.Set(client, "my/key/name", &Person{Name: "Bob"})
The memc package will automatically convert the value []byte into the type
of your Go variable.
value, err := memc.Get[T](client, "my/key/name")
The memc package provides Increment and Decrement for increasing or
decreasing a value by a given delta. Note that the value must already be stored,
and must be in the form of an ASCII string representation of a number. The delta
value must be positive.
err := memc.Set(client, "/my/counter", "100")
Using Increment to increase the counter value by 1.
v, err := memc.Increment("/my/counter", 1)
// v is now 101
Using Decrement to decrease the value by 5.
v, err := memc.Decrement("/my/counter", 5)
// v is now 96
The memcached can handle sharding writes and reads across multiple memcached
instances. It does this by hashing the key space and deterministically choosing
an assigned instance. To enable this behavior simply give the Client each
memcached instance address.
client := memc.New(
[]string{
"10.0.0.1:11211",
"10.0.0.2:11211",
"10.0.0.3:11211",
},
)
The Client sets a default expiration time on each value. This expiration time
can be configured when creating the client.
client := memc.New(
// ...
SetDefaultTTL(2 * time.Minute),
)
The Client maintains an idle connection pool for each memcached instance it
has connected to. The number of idle connections to maintain per instance can be
adjusted.
client := memc.New(
// ...
SetIdleConnections(4),
)
The Client can be closed so that idle connections are closed and no longer
consuming resources. In-flight requests will be closed once complete. Once
closed the client cannot be reused.
_ = memc.Close()
License
The cattlecloud.net/go/memc module is open source under the BSD-3-Clause license.
Documentation
¶
Overview ¶
Package memc provides a modern memcached client for Go.
Index ¶
- Variables
- func Add[T any](c *Client, key string, item T, opts ...Option) error
- func Decrement[T Countable](c *Client, key string, delta T) (T, error)
- func Delete(c *Client, key string) error
- func Get[T any](c *Client, key string) (T, error)
- func Increment[T Countable](c *Client, key string, delta T) (T, error)
- func Set[T any](c *Client, key string, item T, opts ...Option) error
- type Client
- type ClientOption
- type Countable
- type Option
- type Options
Constants ¶
This section is empty.
Variables ¶
var ( ErrCacheMiss = errors.New("memc: cache miss") ErrKeyNotValid = errors.New("memc: key is not valid") ErrNotStored = errors.New("memc: item not stored") ErrNotFound = errors.New("memc: item not found") ErrConflict = errors.New("memc: CAS conflict") ErrExpiration = errors.New("memc: expiration ttl is not valid") ErrClientClosed = errors.New("memc: client has been closed") ErrNegativeInc = errors.New("memc: increment delta must be non-negative") ErrNonNumeric = errors.New("memc: cannot increment non-numeric value") )
Functions ¶
func Add ¶
Add will store the item using the given key, but only if no item currently exists. New items are at the top of the LRU.
Uses Client c to connect to a memcached instance, and automatically handles connection pooling and reuse.
One or more Option(s) may be applied to configure things such as the value expiration TTL or its associated flags.
func Decrement ¶
Decrement will decrement the value associated with the given key by delta.
Note: the value must be an ASCII integer. It must have been initially stored as a string value, e.g. by using Set. The delta value must be positive.
Set(client, "counter", "100") Decrement(client, "counter", 1) // counter = 99
func Delete ¶
Delete will remove the value associated with key from memcached.
Uses Client c to connect to a memcached instance, and automatically handles connection pooling and reuse.
func Get ¶
Get the value associated with the given key.
Uses Client c to connect to a memcached instance, and automatically handles connection pooling and reuse.
func Increment ¶
Increment will increment the value associated with the given key by delta.
Note: the value must be an ASCII integer. It must have been initially stored as a string value, e.g. by using Set. The delta value must be positive.
Set(client, "counter", "100") Increment(client, "counter", 1) // counter = 101
func Set ¶
Set will store the item using the given key, possibly overwriting any existing data. New items are at the top of the LRU.
Uses Client c to connect to a memcached instance, and automatically handles connection pooling and reuse.
One or more Option(s) may be applied to configure things such as the value expiration TTL or its associated flags.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
A Client is used for making network requests to memcached instances.
Use the package functions Set, Get, Delete, etc. by providing this Client to manage data in memcached.
func New ¶
func New(instances []string, opts ...ClientOption) *Client
New creates a new Client capable of sharding across the given set of instances and pooling connections to each instance.
Certain behaviors can be configured by specifying one or more ClientOption options.
type ClientOption ¶
type ClientOption func(c *Client)
func SetDefaultTTL ¶
func SetDefaultTTL(expiration time.Duration) ClientOption
SetDefaultTTL adjusts the default expiration time of values set into the memcached instance(s).
If unset the default expiration TTL is 1 hour.
The expiration time must be more than 1 second, or set to 0 to indicate no expiration time (and values stay in the cache indefinitely).
func SetDialTimeout ¶
func SetDialTimeout(timeout time.Duration) ClientOption
SetDialTimeout adjusts the amount of time to wait on establishing a TCP connection to the memached instance(s).
If unset the default timeout is 5 seconds.
func SetIdleConnections ¶
func SetIdleConnections(count int) ClientOption
SetIdleConnections adjusts the maximum number of idle connections to maintain for each memcached instance.
If unset the default idle connection limit is 1.
Note that idle connections are created on demand, not at startup.
type Countable ¶
Countable represents types that work with Increment and Decrement operations.
Note: memcached does not allow negative values for either operation.
Source Files
Directories