memcached协议

旧版：http://code.sixapart.com/svn/memcached/trunk/server/doc/protocol.txt

新版：https://github.com/memcached/memcached/blob/master/doc/protocol.txt

一、协议

memcached的客户端使用TCP连接同memcached进行交互，memcached服务器监听指定的端口(默认端口是11211)。Client连接到memcached服务器，发送指令，获取数据，然后关闭连接。

通常没有必要发送任何命令来关闭某个会话。客户端可以在任何时候关闭不需要的连接。然而，通常鼓励客户端缓存这些连接，因为memcached服务器本身就被设计成为一个可以支持成百上千个连接的服务器，而客户端缓存了连接后，就可以避免重复的建立连接的开销。

memcached协议中包含两部分数据，文本行和非结构化数据。前者是来自客户端的命令或来自服务器端的响应，后者代表客户端存取的数据。命令以\r\n结尾，数据可以是\r，\n或者\r\n结尾来标识各自部分的结束。

二、键

memcached一般通过key来存储，一个key的长度一般不能超过250字符。key不能包含控制字符或空白字符

三、命令

有三种类型的命令：

1、存储命令：set、add、replace、append、prepend、cas

2、读取命令：get、gets

3、第三种命令，不涉及到非结构化数据。客户端发出这样的命令，服务端会返回响应结果

1、过期时间

过期时间的取值，有两种：一种是Unix时间(自1970.1.1开始到现在的秒数)，另一种是相对当前时间的秒数。如果过期时间的秒数大于60*60*24*30(即30天)，则服务端认为是Unix时间。

2、错误设置

客户端发出的每个命令，服务端可能会返回错误提示字符。错误提示字符有如下三种：

1)  ERROR\r\n ：表示客户端发送的命令不存在

2)  CLIENT_ERROR <error>\r\n ：表示客户端的输入有错误

3)  SERVER_ERROR <error>\r\n ：服务器端的错误

3、存储命令：

命令格式：<command name> <key><flags> <exptime> <bytes> [noreply]\r\n

命令名：如set、add、replace、append、prepend

命令名称	作用
set	存储这个数据
add	存储这个数据，当且仅当这个key不存在的时候
replace	存储这个数据，当且仅当这个key存在
append	将数据存放在已存在的key对应的内容的后面，忽略<flags>和<exptime>
prepend	将数据存放在已存在的key对应的内容的前面，忽略<flags>和<exptime>
cas	存储这个数据，当且仅当该数据自从最后被获取到现在没有被更新

flags：一个任意的32位(旧版本是16位)无符号整数

exptime：过期时间，如果为0，表示永不过期。单位秒

bytes：表示将要存储的数据的字节数，可以为0。要存储的内容的字节数，必须等于该值，不能大于也不能小于。

例子：将一个整数12，存放到memcache中，key为var，flags为1，过期时间为1000，字节数为2

用telnet连接memcached服务器端：

输入命令如下：set var 1 1000 2，然后按回车，之后输入要存储是数据：12，按回车，服务器返回STORED，如下：

通过get命令查看刚才存储的内容：

4、获取命令

格式：

get  <key>*\r\n

gets <key>*\r\n

<key>*，表示可以有多个key，各个key之间用空格隔开。

执行该命令，服务器返回0个或多个item，每个item的格式如下：

VALUE <key> <flags><bytes> [<cas unique>]\r\n

<data block>\r\n

bytes为数据内容的长度，data block为key对应的数据内容

例子：

5、删除命令

格式： delete <key> [noreply]\r\n

noreply参数，告诉服务器不用发送响应

该命令的返回结果，可能是：

DELETE\r\n       表示删除成功

NOT_FOUND\r\n   没有对应的key

例子：

6、增加/减少命令

命令格式：

incr <key> <value> [noreply]\r\n   或   decr <key> <value> [noreply]\r\n

value为要增加或减少的值。

操作成功，服务器返回操作之后的值。

对于decr操作，如果操作之后的值小于0，则置为0

不能直接使用incr和decr，必须先set或者add后再使用，而且值为数字类型，在增加时，存储的区域会扩展。

例子：

7、touch

该命令用来更新已存在的item的过期时间，格式如下：(低版本不支持该命令)

touch <key> <exptime> [noreply]\r\n

执行该命令后，如果返回”TOUCHED\r\n”，则执行成功

8、统计命令

命令格式：

1)    stats\r\n         查看通用的统计信息

2)    stats <args>\r\n

通用统计信息，例子：

具体含义：

名称	类型	含义
pid	32u (32位无符号整数)	memcached server的pid
uptime	32u	memcached server自启动到现在的时间(秒)
time	32u	当前UNIX的时间
version	string	memcached server的版本号
pointer_size	32	操作系统默认的指针大小
curr_items	32u	当前存储的item数目
total_items	32u	server从启动到现在，总共累计存储的item数目
bytes	64u	当前存储item所花费的字节数
curr_connections	32u	当前的客户端连接数
total_connections	32u	server从启动到现在，累计的客户端连接数
connection_structures	32u	server分配的连接结构数
cmd_get	64u	get的次数
cmd_set	64u	set的次数
get_hits	64u	get命中的次数
get_misses	64u	get没有命中，miss的次数
evictions	64u	为新的item释放内存空间而被移除的有效item的数目。如果cache的size比较小，则淘汰策略经常发生
bytes_read	64u	从cache中读取的总字节数
bytes_written	64u	写入cache的总字节数
limit_maxbytes	32u	该memcached server分配的最大内存数量

9、item统计信息

stats命令后面带上参数：items。  返回存储在每个slab的item信息，格式如下：

STAT items:<slabclass>:<stat><value>\r\n

例子：

10、itemsize统计信息

stats命令后面带上参数sizes，返回存储在cache中的总体大小及item数目。

注意：该命令会锁住cache，它会遍历每个item并计算大小，在此之间，我们是无法访问server的，因此要慎重使用该命令。

返回结果的格式如下：

<size> <count>\r\n

其中：

'size' is an approximate size of the item,within 32 bytes.

'count' is the amount of items that existwithin that 32-byte range.

例子：

11、slab统计信息

stats命令带上参数slabs，返回memcached运行期间创建的每个slab的信息。

数据格式：STAT <slabclass>:<stat> <value>\r\n

例子：

名称	含义
chunk_size	每个块的大小。一个item使用一个大小适当的块。
chunks_per_page	一页的块数，一页的默认大小小于等于1M，，chunks_per_page * chunk_size = 1MB。 slab按页分配，每页划分成不同的块
total_pages	分配给slab的页数
total_chunks	分配给slab的块数
used_chunks	已分配给item的块数
free_chunks	未分配给item的块数
free_chunks_end	目前可以使用的块数
mem_requested	请求存储在该slab的字节数
active_slabs	已经分配的slab数量
total_malloced	已经分配给slab的字节数

item存放在slab中，该slab的大小大于或等于该item的大小。mem_requested表示一个slab中所有item的大小。

total_chunks * chunk_size – mem_requested，表示一个slab中所浪费的内存大小。如果有很多浪费，则需要考虑调整slab因子

12、其他命令

1)   flush_all ：执行该命令，将导致memcache中所存在的所有item都失效。也可以指定在一段时间之后失效。例子：

2)   version ： 查看memcache的版本号

3)quit ：关闭连接