> [!NOTE]
> **Note:** To get more information about this package, such as access to older versions, view [this package on pkg.go.dev](https://pkg.go.dev/google.golang.org/appengine/v2/memcache).

<br />

Package memcache provides a client for App Engine's distributed in-memory
key-value store for small chunks of arbitrary data.

The fundamental operations get and set items, keyed by a string.

```go
item0, err := memcache.Get(c, "key")
if err != nil && err != memcache.ErrCacheMiss {
    return err
}
if err == nil {
    fmt.Fprintf(w, "memcache hit: Key=%q Val=[% x]\n", item0.Key, item0.Value)
} else {
    fmt.Fprintf(w, "memcache miss\n")
}
```

<br />

and

```go
item1 := &memcache.Item{
    Key:   "foo",
    Value: []byte("bar"),
}
if err := memcache.Set(c, item1); err != nil {
    return err
}
```

## Variables

### ErrCacheMiss, ErrCASConflict, ErrNoStats, ErrNotStored, ErrServerError

    var (
    	// ErrCacheMiss means that an operation failed
    	// because the item wasn't present.
    	ErrCacheMiss = https://pkg.go.dev/errors.https://pkg.go.dev/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 = https://pkg.go.dev/errors.https://pkg.go.dev/errors#New("memcache: compare-and-swap conflict")
    	// ErrNoStats means that no statistics were available.
    	ErrNoStats = https://pkg.go.dev/errors.https://pkg.go.dev/errors#New("memcache: no statistics available")
    	// ErrNotStored means that a conditional write operation (i.e. Add or
    	// CompareAndSwap) failed because the condition was not satisfied.
    	ErrNotStored = https://pkg.go.dev/errors.https://pkg.go.dev/errors#New("memcache: item not stored")
    	// ErrServerError means that a server error occurred.
    	ErrServerError = https://pkg.go.dev/errors.https://pkg.go.dev/errors#New("memcache: server error")
    )

### Gob, JSON

    var (
    	// Gob is a Codec that uses the gob package.
    	Gob = https://docs.cloud.google.com/appengine/docs/standard/go/reference/services/bundled/latest/memcache#google_golang_org_appengine_v2_memcache_Codec{gobMarshal, gobUnmarshal}
    	// JSON is a Codec that uses the json package.
    	JSON = https://docs.cloud.google.com/appengine/docs/standard/go/reference/services/bundled/latest/memcache#google_golang_org_appengine_v2_memcache_Codec{https://pkg.go.dev/encoding/json.https://pkg.go.dev/encoding/json#Marshal, https://pkg.go.dev/encoding/json.https://pkg.go.dev/encoding/json#Unmarshal}
    )

## Functions

### func Add

    func Add(c https://pkg.go.dev/context.https://pkg.go.dev/context#Context, item *https://docs.cloud.google.com/appengine/docs/standard/go/reference/services/bundled/latest/memcache#google_golang_org_appengine_v2_memcache_Item) https://pkg.go.dev/builtin#error

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

### func AddMulti

    func AddMulti(c https://pkg.go.dev/context.https://pkg.go.dev/context#Context, item []*https://docs.cloud.google.com/appengine/docs/standard/go/reference/services/bundled/latest/memcache#google_golang_org_appengine_v2_memcache_Item) https://pkg.go.dev/builtin#error

AddMulti is a batch version of Add.
appengine.MultiError may be returned.

### func CompareAndSwap

    func CompareAndSwap(c https://pkg.go.dev/context.https://pkg.go.dev/context#Context, item *https://docs.cloud.google.com/appengine/docs/standard/go/reference/services/bundled/latest/memcache#google_golang_org_appengine_v2_memcache_Item) https://pkg.go.dev/builtin#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.

### func CompareAndSwapMulti

    func CompareAndSwapMulti(c https://pkg.go.dev/context.https://pkg.go.dev/context#Context, item []*https://docs.cloud.google.com/appengine/docs/standard/go/reference/services/bundled/latest/memcache#google_golang_org_appengine_v2_memcache_Item) https://pkg.go.dev/builtin#error

CompareAndSwapMulti is a batch version of CompareAndSwap.
appengine.MultiError may be returned.

### func Delete

    func Delete(c https://pkg.go.dev/context.https://pkg.go.dev/context#Context, key https://pkg.go.dev/builtin#string) https://pkg.go.dev/builtin#error

Delete deletes the item for the given key.
ErrCacheMiss is returned if the specified item can not be found.
The key must be at most 250 bytes in length.

### func DeleteMulti

    func DeleteMulti(c https://pkg.go.dev/context.https://pkg.go.dev/context#Context, key []https://pkg.go.dev/builtin#string) https://pkg.go.dev/builtin#error

DeleteMulti is a batch version of Delete.
If any keys cannot be found, an appengine.MultiError is returned.
Each key must be at most 250 bytes in length.

### func Flush

    func Flush(c https://pkg.go.dev/context.https://pkg.go.dev/context#Context) https://pkg.go.dev/builtin#error

Flush flushes all items from memcache.

### func GetMulti

    func GetMulti(c https://pkg.go.dev/context.https://pkg.go.dev/context#Context, key []https://pkg.go.dev/builtin#string) (map[https://pkg.go.dev/builtin#string]*https://docs.cloud.google.com/appengine/docs/standard/go/reference/services/bundled/latest/memcache#google_golang_org_appengine_v2_memcache_Item, https://pkg.go.dev/builtin#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.

### func Increment

    func Increment(c https://pkg.go.dev/context.https://pkg.go.dev/context#Context, key https://pkg.go.dev/builtin#string, delta https://pkg.go.dev/builtin#int64, initialValue https://pkg.go.dev/builtin#uint64) (newValue https://pkg.go.dev/builtin#uint64, err https://pkg.go.dev/builtin#error)

Increment atomically increments the decimal value in the given key
by delta and returns the new value. The value must fit in a uint64.
Overflow wraps around, and underflow is capped to zero. The
provided delta may be negative. If the key doesn't exist in
memcache, the provided initial value is used to atomically
populate it before the delta is applied.
The key must be at most 250 bytes in length.

### func IncrementExisting

    func IncrementExisting(c https://pkg.go.dev/context.https://pkg.go.dev/context#Context, key https://pkg.go.dev/builtin#string, delta https://pkg.go.dev/builtin#int64) (newValue https://pkg.go.dev/builtin#uint64, err https://pkg.go.dev/builtin#error)

IncrementExisting works like Increment but assumes that the key
already exists in memcache and doesn't take an initial value.
IncrementExisting can save work if calculating the initial value is
expensive.
An error is returned if the specified item can not be found.

### func PeekMulti

    func PeekMulti(c https://pkg.go.dev/context.https://pkg.go.dev/context#Context, key []https://pkg.go.dev/builtin#string) (map[https://pkg.go.dev/builtin#string]*https://docs.cloud.google.com/appengine/docs/standard/go/reference/services/bundled/latest/memcache#google_golang_org_appengine_v2_memcache_Item, https://pkg.go.dev/builtin#error)

PeekMulti is a batch version of Peek. It is similar to GetMulti but
additionally populates Item.Timestamps.

### func Set

    func Set(c https://pkg.go.dev/context.https://pkg.go.dev/context#Context, item *https://docs.cloud.google.com/appengine/docs/standard/go/reference/services/bundled/latest/memcache#google_golang_org_appengine_v2_memcache_Item) https://pkg.go.dev/builtin#error

Set writes the given item, unconditionally.

### func SetMulti

    func SetMulti(c https://pkg.go.dev/context.https://pkg.go.dev/context#Context, item []*https://docs.cloud.google.com/appengine/docs/standard/go/reference/services/bundled/latest/memcache#google_golang_org_appengine_v2_memcache_Item) https://pkg.go.dev/builtin#error

SetMulti is a batch version of Set.
appengine.MultiError may be returned.

## Codec

    type Codec struct {
    	Marshal   func(interface{}) ([]https://pkg.go.dev/builtin#byte, https://pkg.go.dev/builtin#error)
    	Unmarshal func([]https://pkg.go.dev/builtin#byte, interface{}) https://pkg.go.dev/builtin#error
    }

Codec represents a symmetric pair of functions that implement a codec.
Items stored into or retrieved from memcache using a Codec have their
values marshaled or unmarshaled.

All the methods provided for Codec behave analogously to the package level
function with same name.

### func (Codec) Add

    func (cd https://docs.cloud.google.com/appengine/docs/standard/go/reference/services/bundled/latest/memcache#google_golang_org_appengine_v2_memcache_Codec) Add(c https://pkg.go.dev/context.https://pkg.go.dev/context#Context, item *https://docs.cloud.google.com/appengine/docs/standard/go/reference/services/bundled/latest/memcache#google_golang_org_appengine_v2_memcache_Item) https://pkg.go.dev/builtin#error

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

### func (Codec) AddMulti

    func (cd https://docs.cloud.google.com/appengine/docs/standard/go/reference/services/bundled/latest/memcache#google_golang_org_appengine_v2_memcache_Codec) AddMulti(c https://pkg.go.dev/context.https://pkg.go.dev/context#Context, items []*https://docs.cloud.google.com/appengine/docs/standard/go/reference/services/bundled/latest/memcache#google_golang_org_appengine_v2_memcache_Item) https://pkg.go.dev/builtin#error

AddMulti is a batch version of Add.
appengine.MultiError may be returned.

### func (Codec) CompareAndSwap

    func (cd https://docs.cloud.google.com/appengine/docs/standard/go/reference/services/bundled/latest/memcache#google_golang_org_appengine_v2_memcache_Codec) CompareAndSwap(c https://pkg.go.dev/context.https://pkg.go.dev/context#Context, item *https://docs.cloud.google.com/appengine/docs/standard/go/reference/services/bundled/latest/memcache#google_golang_org_appengine_v2_memcache_Item) https://pkg.go.dev/builtin#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.

### func (Codec) CompareAndSwapMulti

    func (cd https://docs.cloud.google.com/appengine/docs/standard/go/reference/services/bundled/latest/memcache#google_golang_org_appengine_v2_memcache_Codec) CompareAndSwapMulti(c https://pkg.go.dev/context.https://pkg.go.dev/context#Context, items []*https://docs.cloud.google.com/appengine/docs/standard/go/reference/services/bundled/latest/memcache#google_golang_org_appengine_v2_memcache_Item) https://pkg.go.dev/builtin#error

CompareAndSwapMulti is a batch version of CompareAndSwap.
appengine.MultiError may be returned.

### func (Codec) Get

    func (cd https://docs.cloud.google.com/appengine/docs/standard/go/reference/services/bundled/latest/memcache#google_golang_org_appengine_v2_memcache_Codec) Get(c https://pkg.go.dev/context.https://pkg.go.dev/context#Context, key https://pkg.go.dev/builtin#string, v interface{}) (*https://docs.cloud.google.com/appengine/docs/standard/go/reference/services/bundled/latest/memcache#google_golang_org_appengine_v2_memcache_Item, https://pkg.go.dev/builtin#error)

Get gets the item for the given key and decodes the obtained value into v.
ErrCacheMiss is returned for a memcache cache miss.
The key must be at most 250 bytes in length.

### func (Codec) Set

    func (cd https://docs.cloud.google.com/appengine/docs/standard/go/reference/services/bundled/latest/memcache#google_golang_org_appengine_v2_memcache_Codec) Set(c https://pkg.go.dev/context.https://pkg.go.dev/context#Context, item *https://docs.cloud.google.com/appengine/docs/standard/go/reference/services/bundled/latest/memcache#google_golang_org_appengine_v2_memcache_Item) https://pkg.go.dev/builtin#error

Set writes the given item, unconditionally.

### func (Codec) SetMulti

    func (cd https://docs.cloud.google.com/appengine/docs/standard/go/reference/services/bundled/latest/memcache#google_golang_org_appengine_v2_memcache_Codec) SetMulti(c https://pkg.go.dev/context.https://pkg.go.dev/context#Context, items []*https://docs.cloud.google.com/appengine/docs/standard/go/reference/services/bundled/latest/memcache#google_golang_org_appengine_v2_memcache_Item) https://pkg.go.dev/builtin#error

SetMulti is a batch version of Set.
appengine.MultiError may be returned.

## Item

    type Item struct {
    	// Key is the Item's key (250 bytes maximum).
    	Key https://pkg.go.dev/builtin#string
    	// Value is the Item's value.
    	Value []https://pkg.go.dev/builtin#byte
    	// Object is the Item's value for use with a Codec.
    	Object interface{}
    	// Flags are server-opaque flags whose semantics are entirely up to the
    	// App Engine app.
    	Flags https://pkg.go.dev/builtin#uint32
    	// Expiration is the maximum duration that the item will stay
    	// in the cache.
    	// The zero value means the Item has no expiration time.
    	// Subsecond precision is ignored.
    	// This is not set when getting items.
    	Expiration https://pkg.go.dev/time.https://pkg.go.dev/time#Duration

    	// ItemTimestamps are server values only returned when calling Peek and PeekMulti.
    	// The timestamps are nil when calling Get and GetMulti.
    	Timestamps https://docs.cloud.google.com/appengine/docs/standard/go/reference/services/bundled/latest/memcache#google_golang_org_appengine_v2_memcache_ItemTimestamps
    	// contains filtered or unexported fields
    }

Item is the unit of memcache gets and sets.

### func Get

    func Get(c https://pkg.go.dev/context.https://pkg.go.dev/context#Context, key https://pkg.go.dev/builtin#string) (*https://docs.cloud.google.com/appengine/docs/standard/go/reference/services/bundled/latest/memcache#google_golang_org_appengine_v2_memcache_Item, https://pkg.go.dev/builtin#error)

Get gets the item for the given key. ErrCacheMiss is returned for a memcache
cache miss. The key must be at most 250 bytes in length.

### func Peek

    func Peek(c https://pkg.go.dev/context.https://pkg.go.dev/context#Context, key https://pkg.go.dev/builtin#string) (*https://docs.cloud.google.com/appengine/docs/standard/go/reference/services/bundled/latest/memcache#google_golang_org_appengine_v2_memcache_Item, https://pkg.go.dev/builtin#error)

Peek gets the item for the given key and additionally populates Item.Timestamps.
ErrCacheMiss is returned for a memcache cache miss. The key must be at most 250
bytes in length.

## ItemTimestamps

    type ItemTimestamps struct {
    	// Expiration is related to Item.Expiration but it is a Time (not a Duration),
    	// provided by the server. It is not meant to be set by the user.
    	Expiration *https://pkg.go.dev/time.https://pkg.go.dev/time#Time
    	// LastAccess is the last time the Item was accessed.
    	LastAccess *https://pkg.go.dev/time.https://pkg.go.dev/time#Time
    }

ItemTimestamps are timestamps optionally provided by the server.
See Peek and PeekMulti.

## Statistics

    type Statistics struct {
    	Hits     https://pkg.go.dev/builtin#uint64 // Counter of cache hits
    	Misses   https://pkg.go.dev/builtin#uint64 // Counter of cache misses
    	ByteHits https://pkg.go.dev/builtin#uint64 // Counter of bytes transferred for gets

    	Items https://pkg.go.dev/builtin#uint64 // Items currently in the cache
    	Bytes https://pkg.go.dev/builtin#uint64 // Size of all items currently in the cache

    	Oldest https://pkg.go.dev/builtin#int64 // Age of access of the oldest item, in seconds
    }

Statistics represents a set of statistics about the memcache cache.
This may include items that have expired but have not yet been removed from the cache.

### func Stats

    func Stats(c https://pkg.go.dev/context.https://pkg.go.dev/context#Context) (*https://docs.cloud.google.com/appengine/docs/standard/go/reference/services/bundled/latest/memcache#google_golang_org_appengine_v2_memcache_Statistics, https://pkg.go.dev/builtin#error)

Stats retrieves the current memcache statistics.