memcached文本协议

以下是很早之前写的memcached文件协议介绍，重新发布一次。

 

考虑到memcached1.2与memcached1.1的协议有些不同，分别论述。

[ 返回的错误描述信息 ]
返回的错误描述信息分为三种，带有不同的关键字头：

普通错误信息，比如指令不存在
ERROR/r/n

客户端错误
CLIENT_ERROR <错误信息>/r/n

服务器端错误
SERVER_ERROR <错误信息>/r/n

[ 数据存储指令 ]
数据存储是基本的功能，客户端通过命令传递数据，服务器端接收后进行相应处理。

memcache1.1指令格式：
<command name> <key> <flags> <exptime> <bytes>/r/n
<data block>/r/n

memcache1.2指令格式：
<command name> <key> <flags> <exptime> <bytes> [noreply]/r/n
<data block>/r/n

cas <key> <flags> <exptime> <bytes> <cas unique> [noreply]/r/n

<command name> - 命令名
-------------------------
主要的数据存储命令有:

memcached1.1支持以下命令：
1、set
保存数据，如果数据已存在（key相同）则覆盖；
2、add
保存数据，如果数据已存在（key相同）则返回错误：NOT_STORED；
3、replace
替换数据，如果数据不存在（没有对应的key存在）则返回错误：NOT_STORED；

memcached1.2在memcached1.1的命令格式最后添加一个可选项noreply，即禁止了服务端的返回信息，此外，memcached1.2增加了几个命令：
4、append
修改数据，把数据添加到已经存在的数据的后面，如果数据不存在（没有对应的key存在），则返回错误：NOT_STORED；
5、prepend
修改数据，把数据添加到已经存在的数据的前面，如果数据不存在（没有对应的key存在），则返回错误：NOT_STORED；
6、cas
check and set,首先介绍一下参数<cas unique>，这是服务端系统分配的一个64位唯一序列号，这是一个计数器，他随着服务端数据的增加或者更新而递增，删除数据不递减该数值，系统 中当前分配到的最大cas unique值就是系统中到目前为止存在过的item的总数（这非常类似于mysql）。命令gets会返回这个唯一序列号。cas命令更新那些自从上次 操作之后没有更新过的数据，这里比较绕，看个例子吧：
首先存储一个新的item（key=1，value=kenbin）
set 1 0 0 6
kenbin
STORED
用key提取数据，可以看出此时cas unique=1
gets 1
VALUE 1 0 6 1
kenbin
END
增加一个新的item（key=2，value=bin）
add 2 0 0 3
bin
STORED
提取数据，可以看出此时的两个item的cas unique分别为1和2
gets 1
VALUE 1 0 6 1
kenbin
END
gets 2
VALUE 2 0 3 2
bin
END
修改key=1的数据
set 1 0 0 11
kenbinzhang
STORED
再次提取数据，key=1的item的cas unique已经从1变为3了
gets 1
VALUE 1 0 11 3
kenbinzhang
END
gets 2
VALUE 2 0 3 2
bin
END
此 时用cas去更新cas unique=1的item（key=1，value=kenbin），更新失败了，为什么会失败呢？因为自从第一次对其操作（set 1 0 0 6/r/nkenbin/r/n）后又进行了一次操作（set 1 0 0 11/r/nkenbinzhang/r/n），所以这个item是自从上次操作之后已经被更新过了的，返回EXSITS错误（意思：cas unique=1，key=1，value=kenbin的item已经被更新过一次了，它的结果已经存在了，就是cas unique=3，key=1，value=kenbinzhang的那个item）
cas 1 0 0 3 1
ken
EXISTS
如果对cas unique=3，key=1，value=kenbinzhang的item进行cas操作，则从上面推论可以看出，是可以成功了，不妨一试
cas 1 0 0 3 3
ken
STORED
gets 1
VALUE 1 0 3 4
ken
END

<key> - 键值
-------------------------
保存在服务器上的数据的唯一标识符，必须是跟其他的key不冲突，否则会覆盖掉原来的数据，这个key是为了能够准确的存取一个数据项目

<flags> - 标志位
-------------------------
标志位是一个16位的无符号整形数据(memcached1.2升级到32位)，客户端可以把它用作位域来存储数据的特殊信息，服务器不处理标志位，当客户端提取数据的时候，返回给客户端

<exptime> - 有效期限
-------------------------
是数据在服务器上的有效期限，如果是0，则数据永远有效，单位是秒，Memcache服务器端会把一个数据的有效期设置为当前Unix时间+设置的有效时间

<bytes> - 数据长度
-------------------------
block data块数据的长度，一般在这个长度结束的下一行跟着block data数据内容，发送完数据以后，客户端一般等待服务器端的返回，服务器端的返回：
数据保存成功
STORED/r/n
数据保存失败，一般是因为服务器端已存在key
NOT_STORED/r/n

[ 数据提取命令 ]
从服务器端提取数据的命令。

memcached1.1提供下面命令：
1、get <key>*/r/n

memcached1.2又提供了一个提取命令：
2、gets <key>*/r/n

<key>* - 键值列表
-------------------------
可以同时提取多个key值对应的数据，发送这个指令以后，等待服务器的返回。
如果服务器端没有任何数据，则是返回：END/r/n，表明不存在这个key，也即没有符合的数据。

如果存在数据，则get返回指定格式：
VALUE <key> <flags> <bytes>/r/n
<data block>/r/n
gets返回指定格式：
VALUE <key> <flags> <bytes> <cas unique>/r/n
<data block>/r/n

返回的数据以VALUE关键字开始的，后面跟着key和flags，以及数据长度，第二行跟着数据块。
<key>:发送过来指令的key内容
<flags>:数据存储时候设置的flags
<bytes>:数据长度
<cas unique>:系统唯一序列号
<data block>:提取的数据块内容

[ 数据删除指令 ]
指定key值，删除数据。

memcached1.1提供的指令：
delete <key> [<time>]/r/n

memcached1.2提供的指令：
delete <key> [<time>] [noreply]/r/n

<key> - 键值
-------------------------
key是你希望在服务器上删除数据的key键

<time> - 等待时间
-------------------------
按照秒为单位，这是个可选项，如果没有指定这个值，那么服务器上key数据将马上被删除，如果设置了这个值，那么数据将在等待时间后把数据清除，该项缺省为0，就是马上被删除。删除数据后，服务器端会返回：
DELETED/r/n
删除数据成功
NOT_FOUND/r/n
这个key没有在服务器上找到

如果要删除所有服务器上的数据，可以使用flash_all指令，格式：
flush_all/r/n
这个指令执行后，服务器上所有缓存的数据都被删除，并且返回：
OK/r/n

noreply - 禁止服务器返回信息
-------------------------
memcached1.2增加的选项

[ 统计指令 ]
如果想了解当前memcached服务器的状态和版本等信息，可以使用状态查询指令。

如果想了解当前所有memcached服务器运行的状态信息，可以使用stats指令，格式：
stats/r/n
-------------------------
服务器将返回每行按照 STAT 开始的状态信息，包括守护进程的pid、版本、保存的项目数量、内存占用、最大内存限制等等信息。
memcached1.1返回的信息如下：
stats
STAT pid 11652
STAT uptime 11643
STAT time 1208694201
STAT version 1.1.13
STAT pointer_size 32
STAT rusage_user 0.040000
STAT rusage_system 0.080000
STAT curr_items 0
STAT total_items 3
STAT bytes 0
STAT curr_connections 1
STAT total_connections 3
STAT connection_structures 2
STAT cmd_get 11
STAT cmd_set 4
STAT get_hits 7
STAT get_misses 4
STAT bytes_read 265
STAT bytes_written 346
STAT limit_maxbytes 67108864
END
memcached1.2返回的信息如下：
stats
STAT pid 13375
STAT uptime 2147
STAT time 1208694456
STAT version 1.2.5
STAT pointer_size 32
STAT rusage_user 0.020000
STAT rusage_system 0.010000
STAT curr_items 0
STAT total_items 0
STAT bytes 0
STAT curr_connections 2
STAT total_connections 3
STAT connection_structures 3
STAT cmd_get 0
STAT cmd_set 0
STAT get_hits 0
STAT get_misses 0
STAT evictions 0
STAT bytes_read 7
STAT bytes_written 0
STAT limit_maxbytes 67108864
STAT threads 1
END
pid:守护进程的id
uptime:进程已经运行的时间，以秒为单位
time:当前的unix时间
version:服务器版本
pointer_size:操作系统默认的指针长度
rusage_user:进程累计的user time（秒：毫秒）
rusage_system:进程累计的system time（秒：毫秒）
curr_items:当前的items数量
total_items:进程启动开始存储过的items数量
bytes:当前用于存储items的byte数量
curr_connections:打开的连接数量
total_connections:进程启动开始打开过的连接数量
connection_structures:服务分配的连接结构数量
cmd_get:提取请求次数
cmd_set:存储请求次数
get_hits:get命中次数
get_misses:get未命中次数
evictions:为了添加新item而回收的合法item数量
bytes_read:服务从network读取的byte数量
bytes_written:服务写入network的byte数量
limit_maxbytes:服务可使用的用于存储数据的最大值
threads:被请求的工作线程数量

如果只是想获取部分项目的信息，可以指定参数，格式：
stats <args>/r/n
-------------------------
这个指令将只返回指定参数的项目状态信息

stats items/r/n
-------------------------
该命令按照slabclass分类返回items的统计信息。
返回结果：
STAT items:<slabclass>:<stat> <value>/r/n
<stat>在memcached1.1有两个统计项：
1、number
存储在该slabclass中的item数量，过期的item不会被除外
2、age
LRU中最老的item经历的时间（秒）
memcached1.2中添加了两项：
3、evicted
从LRU中清除未过期的item的次数
4、outofmemory
该slabclass中已经无法存储新item的次数，一般是以-M启动了服务或者清除item失败

stats sizes/r/n
-------------------------
该命令按照size分类返回items的统计信息。item的size按照最接近32的整数倍的数值归类。
例如，内存中cache了三条item，两个长度是32，一个长度是66。则返回信息如下：
stats sizes
64 2
96 1
END
item的长度是32+key长度+value长度

stats slabs/r/n
-------------------------
统计slabs相关信息，按照slabclass分类。
返回结果：
STAT <slabclass>:<stat> <value>/r/n
STAT <stat> <value>/r/n
例如：
stats slabs
STAT 1:chunk_size 88
STAT 1:chunks_per_page 11915
STAT 1:total_pages 1
STAT 1:total_chunks 11915
STAT 1:used_chunks 11915
STAT 1:free_chunks 0
STAT 1:free_chunks_end 11914
STAT active_slabs 1
STAT total_malloced 1048520
END
chunk_size:每个chunk（块）使用的空间数量，一个item存储到一个近似大小的chunk中
chunk_per_page:每page存在的chunk数量，slabs是按页（page）分配的，一页一般为1M，每个slab(也即每页)又划分为若干chunk，这里涉及到memcached的内存管理，这里不多解释，可以参考后面的附文。
total_pages:该slabclass分配到的page数量
total_chunks:该slabclass拥有的chunk数量
used_chunks:已经分配给item的chunk数量（不一定已经装填了item）
free_chunks:尚未分配给item的chunk数量，或者由delete释放的chunk
free_chunks_end:slabclass中最后一页的自由块数量，即该slabclass尚有多少自由块可以用来装填item
active_slabs:已分配的slabclass数量
total_malloced:已分配给slab page的内存数量
[ 其他指令 ]
如果只是想单独了解当前版本信息，可以使用version指令，格式：
version/r/n
-------------------------
将返回以 VERSION 开头的版本信息

如果想结束当前连接，使用quit指令，格式：
quit/r/n
-------------------------
将断开当前连接

另外还有其他指令，包括incr, decr等。