memcached协议

Protocol

Clients of memcached communicate with server through TCP connections. (A UDP interface is also available; details are below under “UDP protocol.”) A given running memcached server listens on some (configurable) port; clients connect to that port, send commands to the server, read responses, and eventually close the connection.

There is no need to send any command to end the session. A client may just close the connection at any moment it no longer needs it. Note, however, that clients are encouraged to cache their connections rather than reopen them every time they need to store or retrieve data. This is because memcached is especially designed to work very efficiently with a very large number (many hundreds, more than a thousand if necessary) of open connections. Caching connections will eliminate the overhead associated with establishing a TCP connection (the overhead of preparing for a new connection on the server side is insignificant compared to this).

There are two kinds of data sent in the memcache protocol: text lines

and unstructured data. Text lines are used for commands from clients

and responses from servers. Unstructured data is sent when a client

wants to store or retrieve data. The server will transmit back

unstructured data in exactly the same way it received it, as a byte

stream. The server doesn’t care about byte order issues in

unstructured data and isn’t aware of them. There are no limitations on

characters that may appear in unstructured data; however, the reader

of such data (either a client or a server) will always know, from a

preceding text line, the exact length of the data block being

transmitted.

Text lines are always terminated by \r\n. Unstructured data is _also_

terminated by \r\n, even though \r, \n or any other 8-bit characters

may also appear inside the data. Therefore, when a client retrieves

data from a server, it must use the length of the data block (which it

will be provided with) to determine where the data block ends, and not

the fact that \r\n follows the end of the data block, even though it

does.

Keys

Data stored by memcached is identified with the help of a key. A key

is a text string which should uniquely identify the data for clients

that are interested in storing and retrieving it. Currently the

length limit of a key is set at 250 characters (of course, normally

clients wouldn’t need to use such long keys); the key must not include

control characters or whitespace.

Commands

There are three types of commands.

Storage commands (there are three: “set”, “add” and “replace”) ask the

server to store some data identified by a key. The client sends a

command line, and then a data block; after that the client expects one

line of response, which will indicate success or faulure.

Retrieval commands (there is only one: “get”) ask the server to

retrieve data corresponding to a set of keys (one or more keys in one

request). The client sends a command line, which includes all the

requested keys; after that for each item the server finds it sends to

the client one response line with information about the item, and one

data block with the item’s data; this continues until the server

finished with the “END” response line.

All other commands don’t involve unstructured data. In all of them,

the client sends one command line, and expects (depending on the

command) either one line of response, or several lines of response

ending with “END” on the last line.

A command line always starts with the name of the command, followed by

parameters (if any) delimited by whitespace. Command names are

lower-case and are case-sensitive.

Some commands involve a client sending some kind of expiration time

(relative to an item or to an operation requested by the client) to

the server. In all such cases, the actual value sent may either be

Unix time (number of seconds since January 1, 1970, as a 32-bit

value), or a number of seconds starting from current time. In the

latter case, this number of seconds may not exceed 60*60*24*30 (number

of seconds in 30 days); if the number sent by a client is larger than

that, the server will consider it to be real Unix time value rather

than an offset from current time.

Error strings

Each command sent by a client may be answered with an error string

from the server. These error strings come in three types:

- “ERROR\r\n”

means the client sent a nonexistent command name.

- “CLIENT_ERROR <error>\r\n”

means some sort of client error in the input line, i.e. the input

doesn’t conform to the protocol in some way. <error> is a

human-readable error string.

- “SERVER_ERROR <error>\r\n”

means some sort of server error prevents the server from carrying

out the command. <error> is a human-readable error string. In cases

of severe server errors, which make it impossible to continue

serving the client (this shouldn’t normally happen), the server will

close the connection after sending the error line. This is the only

case in which the server closes a connection to a client.

In the descriptions of individual commands below, these error lines

are not again specifically mentioned, but clients must allow for their

possibility.

Storage commands

First, the client sends a command line which looks like this:

<command name> <key> <flags> <exptime> <bytes>\r\n

- <command name> is “set”, “add” or “replace”

• “set” means “store this data”.
• “add” means “store this data, but only if the server *doesn’t* already
  hold data for this key”.
• “replace” means “store this data, but only if the server *does*
  already hold data for this key”.

- <key> is the key under which the client asks to store the data

- <flags> is an arbitrary 16-bit unsigned integer (written out in

decimal) that the server stores along with the data and sends back

when the item is retrieved. Clients may use this as a bit field to

store data-specific information; this field is opaque to the server.

- <exptime> is expiration time. If it’s 0, the item never expires

(although it may be deleted from the cache to make place for other

items). If it’s non-zero (either Unix time or offset in seconds from

current time), it is guaranteed that clients will not be able to

retrieve this item after the expiration time arrives (measured by

server time).

- <bytes> is the number of bytes in the data block to follow, *not*

including the delimiting \r\n. <bytes> may be zero (in which case

it’s followed by an empty data block).

After this line, the client sends the data block:

<data block>\r\n

- <data block> is a chunk of arbitrary 8-bit data of length <bytes>

from the previous line.

After sending the command line and the data blockm the client awaits

the reply, which may be:

- “STORED\r\n”

to indicate success.

- “NOT_STORED\r\n”

to indicate the data was not stored, but not

because of an error. This normally means that either that the

condition for an “add” or a “replace” command wasn’t met, or that the

item is in a delete queue (see the “delete” command below).

Retrieval command

The retrieval command looks like this:

get <key>*\r\n

- <key>* means one or more key strings separated by whitespace.

After this command, the client expects zero or more items, each of

which is received as a text line followed by a data block. After all

the items have been transmitted, the server sends the string

“END\r\n”

to indicate the end of response.

Each item sent by the server looks like this:

VALUE <key> <flags> <bytes>\r\n

<data block>\r\n

- <key> is the key for the item being sent

- <flags> is the flags value set by the storage command

- <bytes> is the length of the data block to follow, *not* including

its delimiting \r\n

- <data block> is the data for this item.

If some of the keys appearing in a retrieval request are not sent back

by the server in the item list this means that the server does not

hold items with such keys (because they were never stored, or stored

but deleted to make space for more items, or expired, or explicitly

deleted by a client).

Deletion

The command “delete” allows for explicit deletion of items:

delete <key> <time>\r\n

- <key> is the key of the item the client wishes the server to delete

- <time> is the amount of time in seconds (or Unix time until which)

the client wishes the server to refuse “add” and “replace” commands

with this key. For this amount of item, the item is put into a

delete queue, which means that it won’t possible to retrieve it by

the “get” command, but “add” and “replace” command with this key

will also fail (the “set” command will succeed, however). After the

time passes, the item is finally deleted from server memory.

The parameter <time> is optional, and, if absent, defaults to 0

(which means that the item will be deleted immediately and further

storage commands with this key will succeed).

The response line to this command can be one of:

- “DELETED\r\n”

to indicate success

- “NOT_FOUND\r\n”

to indicate that the item with this key was not found.

See the “flush_all” command below for immediate invalidation

of all existing items.

Increment/Decrement

Commands “incr” and “decr” are used to change data for some item

in-place, incrementing or decrementing it. The data for the item is

treated as decimal representation of a 32-bit unsigned integer. If the

current data value does not conform to such a representation, the

commands behave as if the value were 0. Also, the item must already

exist for incr/decr to work; these commands won’t pretend that a

non-existent key exists with value 0; instead, they will fail.

The client sends the command line:

incr <key> <value>\r\n

或

decr <key> <value>\r\n

- <key> is the key of the item the client wishes to change

- <value> is the amount by which the client wants to increase/decrease

the item. It is a decimal representation of a 32-bit unsigned integer.

The response will be one of:

- “NOT_FOUND\r\n”

to indicate the item with this value was not found

- <value>\r\n , where <value> is the new value of the item’s data,

after the increment/decrement operation was carried out.

Note that underflow in the “decr” command is caught: if a client tries

to decrease the value below 0, the new value will be 0. Overflow in

the “incr” command is not checked.

Note also that decrementing a number such that it loses length isn’t

guaranteed to decrement its returned length. The number MAY be

space-padded at the end, but this is purely an implementation

optimization, so you also shouldn’t rely on that.

Statistics

The command “stats” is used to query the server about statistics it

maintains and other internal data. It has two forms. Without

arguments:

 stats\r\n

it causes the server to output general-purpose statistics and

settings, documented below. In the other form it has some arguments:

stats <args>\r\n

Depending on <args>, various internal data is sent by the server. The

kinds of arguments and the data sent are not documented in this vesion

of the protocol, and are subject to change for the convenience of

memcache developers.

General-purpose statistics

Upon receiving the “stats” command without arguments, the server sents

a number of lines which look like this:

STAT <name> <value>\r\n

The server terminates this list with the line

END\r\n

In each line of statistics, <name> is the name of this statistic, and

<value> is the data. The following is the list of all names sent in

response to the “stats” command, together with the type of the value

sent for this name, and the meaning of the value.

In the type column below, “32u” means a 32-bit unsigned integer, “64u”

means a 64-bit unsigner integer. ‘32u:32u’ means two 32-but unsigned

integers separated by a colon.

Other commands

“flush_all” is a command with an optional numeric argument. It always succeeds, and the server sends “OK\r\n” in response. Its effect is to invalidate all existing items immediately (by default) or after the expiration specified. After invalidation none of the items will be returned in response to a retrieval command (unless it’s stored again under the same key *after* flush_all has invalidated the items). flush_all doesn’t actually free all the memory taken up by existing items; that will happen gradually as new items are stored. The most precise definition of what flush_all does is the following: it causes all items whose update time is earlier than the time at which flush_all was set to be executed to be ignored for retrieval purposes.

“version” is a command with no arguments:

version\r\n

In response, the server sends

“VERSION <version>\r\n”

where <version> is the version string for the server.

“quit” is a command with no arguments:

quit\r\n

Upon receiving this command, the server closes the connection. However, the client may also simply close the connection when it no longer needs it, without issuing this command.

UDP protocol

For very large installations where the number of clients is high enough that the number of TCP connections causes scaling difficulties, there is also a UDP-based interface. The UDP interface does not provide guaranteed delivery, so should only be used for operations that aren’t required to succeed; typically it is used for “get” requests where a missing or incomplete response can simply be treated as a cache miss.

Each UDP datagram contains a simple frame header, followed by data in the same format as the TCP protocol described above. In the current implementation, requests must be contained in a single UDP datagram, but responses may span several datagrams. (The only common requests that would span multiple datagrams are huge multi-key “get” requests and “set” requests, both of which are more suitable to TCP transport for reliability reasons anyway.)

The frame header is 8 bytes long, as follows (all values are 16-bit integers in network byte order, high byte first):

• 0-1 Request ID
• 2-3 Sequence number
• 4-5 Total number of datagrams in this message
• 6-7 Reserved for future use; must be 0

The request ID is supplied by the client. Typically it will be a monotonically increasing value starting from a random seed, but the client is free to use whatever request IDs it likes. The server’s response will contain the same ID as the incoming request. The client uses the request ID to differentiate between responses to outstanding requests if there are several pending from the same server; any datagrams with an unknown request ID are probably delayed responses to an earlier request and should be discarded.