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.
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" ) }
and
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
=
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"
)
//
ErrNoStats
means
that
no
statistics
were
available
.
ErrNoStats
=
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
=
errors
.
New
(
"memcache: item not stored"
)
//
ErrServerError
means
that
a
server
error
occurred
.
ErrServerError
=
errors
.
New
(
"memcache: server error"
)
)
Gob, JSON
var
(
//
Gob
is
a
Codec
that
uses
the
gob
package
.
Gob
=
Codec
{
gobMarshal
,
gobUnmarshal
}
//
JSON
is
a
Codec
that
uses
the
json
package
.
JSON
=
Codec
{
json
.
Marshal
,
json
.
Unmarshal
}
)
Functions
func Add
Add writes the given item, if no value already exists for its key. ErrNotStored is returned if that condition is not met.
func AddMulti
AddMulti is a batch version of Add. appengine.MultiError may be returned.
func CompareAndSwap
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
CompareAndSwapMulti is a batch version of CompareAndSwap. appengine.MultiError may be returned.
func Delete
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
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
Flush flushes all items from memcache.
func GetMulti
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
context
.
Context
,
key
string
,
delta
int64
,
initialValue
uint64
)
(
newValue
uint64
,
err
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
context
.
Context
,
key
string
,
delta
int64
)
(
newValue
uint64
,
err
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
PeekMulti is a batch version of Peek. It is similar to GetMulti but additionally populates Item.Timestamps.
func Set
Set writes the given item, unconditionally.
func SetMulti
SetMulti is a batch version of Set. appengine.MultiError may be returned.
Codec
type
Codec
struct
{
Marshal
func
(
interface
{})
([]
byte
,
error
)
Unmarshal
func
([]
byte
,
interface
{})
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
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
AddMulti is a batch version of Add. appengine.MultiError may be returned.
func (Codec) CompareAndSwap
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
CompareAndSwapMulti is a batch version of CompareAndSwap. appengine.MultiError may be returned.
func (Codec) Get
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
Set writes the given item, unconditionally.
func (Codec) SetMulti
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
string
//
Value
is
the
Item
's value.
Value
[]
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
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
time
.
Duration
//
ItemTimestamps
are
server
values
only
returned
when
calling
Peek
and
PeekMulti
.
//
The
timestamps
are
nil
when
calling
Get
and
GetMulti
.
Timestamps
ItemTimestamps
//
contains
filtered
or
unexported
fields
}
Item is the unit of memcache gets and sets.
func Get
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
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
*
time
.
Time
// LastAccess is the last time the Item was accessed.
LastAccess
*
time
.
Time
}
ItemTimestamps are timestamps optionally provided by the server. See Peek and PeekMulti.
Statistics
type
Statistics
struct
{
Hits
uint64
// Counter of cache hits
Misses
uint64
// Counter of cache misses
ByteHits
uint64
// Counter of bytes transferred for gets
Items
uint64
// Items currently in the cache
Bytes
uint64
// Size of all items currently in the cache
Oldest
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
context
.
Context
)
(
*
Statistics
,
error
)
Stats retrieves the current memcache statistics.
