16.6.3.1 Basic memcached Operations

The interface to memcached supports the
following methods for storing and retrieving information in the
cache, and these are consistent across all the different APIs,
although the language specific mechanics might be different:

get(key):
Retrieves information from the cache. Returns the value
associated with the key if the specified key exists. Returns
NULL, nil,
undefined, or the closest equivalent in
the corresponding language, if the specified key does not
exist.

set(key,
value [,
expiry]): Sets the
item associated with a key in the cache to the specified
value. This either updates an existing item if the key
already exists, or adds a new key/value pair if the key
doesn't exist. If the expiry time is specified, then the
item expires (and is deleted) when the expiry time is
reached. The time is specified in seconds, and is taken as a
relative time if the value is less than 30 days
(30*24*60*60), or an absolute time (epoch) if larger than
this value.

add(key,
value [,
expiry]): Adds the key
and associated value to the cache, if the specified key does
not already exist.

replace(key,
value [,
expiry]): Replaces the
item associated with the specified key,
only if the key already exists. The new value is given by
the value parameter.

delete(key [,
time]): Deletes the
key and its associated item from the
cache. If you supply a time, then adding
another item with the specified key is
blocked for the specified period.

incr(key ,
value): Increments the
item associated with the key by the
specified value.

decr(key ,
value): Decrements the
item associated with the key by the
specified value.

flush_all: Invalidates (or expires) all
the current items in the cache. Technically they still exist
(they are not deleted), but they are silently destroyed the
next time you try to access them.

In all implementations, most or all of these functions are
duplicated through the corresponding native language interface.

When practical, use memcached to store full
items, rather than caching a single column value from the
database. For example, when displaying a record about an object
(invoice, user history, or blog post), load all the data for the
associated entry from the database, and compile it into the
internal structure that would normally be required by the
application. Save the complete object in the cache.

Complex data structures cannot be stored directly. Most
interfaces serialize the data for you, that is, put it in a
textual form that can reconstruct the original pointers and
nesting. Perl uses Storable, PHP uses
serialize, Python uses
cPickle (or Pickle) and
Java uses the Serializable interface. In most
cases, the serialization interface used is customizable. To
share data stored in memcached instances
between different language interfaces, consider using a common
serialization solution such as JSON (Javascript Object
Notation).