memcached文档

#telnet 127.0.0.1 12345

^stats

^stats items

^stats cachedump 1 10

^stats cachedump 2 10

协议

memcached的客户端使用TCP链接与 服务器通讯。（UDP接口也同样有效，参考后文的“UDP协议”）一个运行中的memcached服务器监视一些（可设置）端口。客户端连接这些端口，发送命令到服务器，读取回应，最后关闭连接。

结束会话不需要发送任何命令。当不再需memcached服务时，要客户端可以在任何时候关闭连接。需要注意的是，鼓励客户端缓存这些连接，而不是每次需要存取数据时都重新打开连接。这是因为memcached被特意设计成及时开启很多连接也能够高效的工作（数百个，上千个如果需要的话）。缓存这些连接，可以消除建立连接所带来的开销（/*/相对而言，在服务器端建立一个新连接的准备工作所带来的开销，可以忽略不计。）。

在memcache协议中发送的数据分两种：文本行和 自由数据。文本行被用于来自客户端的命令和服务器的回应。自由数据用于客户端从服务器端存取数据时。同样服务器会以字节流的方式传回自由数据。/*/服务器不用关心自由数据的字节顺序。自由数据的特征没有任何限制；但是通过前文提到的文本行，这项数据的接受者（服务器或客户端），便能够精确地获知所发送的数据库的长度。

文本行固定以“\r\n”(回车符紧跟一个换行符)结束。自由数据也是同样会以“\r\n”结束，但是\r(回车符)、\n(换行符)，以及任何其他8位字符，均可出现在数据中。因此，当客户端从服务器取回数据时，必须使用数据区块的长度来确定数据区块的结束位置，而不要依据数据区块末尾的“\r\n”，即使它们固定存在于此。

键值

存储在memcached中的数据通过键值来标识。键值是一个文本字符串，对于需要存取这项数据的客户端而言，它必须是唯一的。键值当前的长度限制设定为250字符（当然，客户端通常不会用到这么长的键）；键值中不能使用制表符和其他空白字符（例如空格，换行等）。

存储数据

首先客户端发送以下命令行："set","add", "replace", "append"和"prepend"。

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

cas <key> <flags><exptime> <bytes> <cas unqiue>\r\n

set：存储数据。

add：添加数据，只有当服务器还没有保存此键值（key）数据时，才添加。

replace:取代数据，只有当服务器已经保存此键值(key)数据时，才能取代。

append：在此键值所保存数据内容的后面添加数据。

prepend：在此键值所保存数据内容的前面添加数据。

cas：只有上次已经取出该键值的数据并没有被其他人更新才存入。

append和prepend命令不需要flags和exptime，因为它们只更新数据的一部分。

<key>是接下来的客户端所要求储存的数据的键值

<flags>是在取回内容时，与数据和发送块一同保存服务器上的任意16位无符号整形（用十进制来书写）。客户端可以用它作为“位域”来存储一些特定的信息；它对服务器是不透明的。

<exptime>是终止时间。如果为0，该项永不过期(虽然它可能被删除，以便为其他缓存项目腾出位置)。如果非0（Unix时间戳或当前时刻的秒偏移），到达终止时间后，客户端无法再获得这项内容。

<bytes>是随后的数据区块的字节长度，不包括用于分野的“\r\n”。它可以是0（这时后面跟随一个空的数据区块）。

<noreply>可选参数，让服务器不用回复操作信息。

在这一行以后，客户端发送数据区块。

<data block>\r\n：<datablock>是大段的8位数据，其长度由前面的命令行中的<bytes>指定。

发送命令行和数据区块以后，客户端等待回复，可能的回复如下：

“STROED\r\n”：表明成功。

“NOT_STROED\r\n”：表示失败。

"NOT_FOUND\r\n"：表示用cas来存储数据时该数据不存在或已删除。

表明数据没有被存储，但不是因为发生错误。这通常意味着add或replace命令的条件不成立，或者，项目已经位列删除队列。

取出数据命令：

“get <key>*\r\n”：

<key>*表示一个或多个键值，由空格隔开的字串这行命令以后，客户端的等待0个或多个项目，每项都会收到一行文本，然后跟着数据区块。所有项目传送完毕后，服务器发送以下字串：

服务器用以下形式发送每项内容：

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

<data block>\r\n

<key>是所发送的键名

<flags>是存储命令所设置的记号

<bytes>是随后数据块的长度，不包括它的界定符“\r\n”

<data block>是发送的数据

<cas unique>一个64位整型用来表示特殊内容。

如果在取回请求中发送了一些键名，而服务器没有送回项目列表，这意味着服务器没这些键名（可能因为它们从未被存储，或者为给其他内容腾出空间而被删除，或者到期，或者被已客户端删除）。

删除命令：

命令“delete”允许从外部删除内容：

delete<key> <time> [noreply]\r\n

<key>是客户端希望服务器删除的内容的键名

<time>是一个单位为秒的时间（或代表直到某一刻的Unix时间），在该时间内服务器会拒绝对于此键名的“add”和“replace”命令。此时内容被放入delete队列，无法再通过“get”得到该内容，也无法是用“add”和“replace”命令（但是“set”命令可用）。直到指定时间，这些内容被最终从服务器的内存中彻底清除。

<time>参数是可选的，缺省为0（表示内容会立刻清除，并且随后的存储命令均可用）。

"noreply"可选参数，告诉服务器不用回复信息。

此命令有一行回应：

“DELETED\r\n”表示执行成功。

“NOT_FOUND\r\n”表示没有找到这项内容。

加/减命令

命令 “incr”和 “decr”被用来修改数据，当一些内容需要替换、增加或减少时。这些数据必须是十进制的64位无符号整新。如果不是，则当作0来处理。修改的内容必须存在，当使用“incr”/“decr”命令修改不存在的内容时，不会被当作0处理，而是操作失败。

客户端发送命令行：

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

或

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

<key>是客户端希望修改的内容的建名

<value>是客户端要增加/减少的总数。

"noreply"可选参数，告诉服务器不用回复信息。

回复为以下集中情形：

“NOT_FOUND\r\n”指示该项内容的值，不存在。

<value>\r\n，<value>是增加/减少。

注意”decr”命令发生下溢：如果客户端尝试减少的结果小于0时，结果会是0。”incr”命令不会发生溢出。

状态命令

命令”stats”被用于查询服务器的运行状态和其他内部数据。有两种格式。不带参数的：

stats\r\n

这会在随后输出各项状态、设定值和文档。另一种格式带有一些参数：
stats<args>\r\n

通过<args>，服务器传回各种内部数据，随时可能发生变动。

收到无参数的”stats”命令后，服务器发送多行内容，如下：

STAT <name><value>\r\n

服务器用以下一行来终止这个清单：

END\r\n

在每行状态中，<name>是状态的名字，<value>使状态的数据。下图，是所有的状态名称，数据类型，和数据代表的含义。

在“类型”一列中，”32u”表示32位无符号整型，”64u”表示64位无符号整型，”32u:32u”表示用冒号隔开的两个32位无符号整型。

Name Type Meaning

----------------------------------

pid 32u服务器进程ID

uptime 32u服务器运行时间（秒）

time 32u服务器当前unix时间（秒）

version string服务器版本号

pointer_size 32默认主机操作系统的指令位数（32或64）

rusage_user 32u:32u该进程累计用户时间（秒：微妙）

rusage_system 32u:32u该进程累计的系统时间（秒：微妙）

curr_items 32u服务器当前存储的内容数量

total_items 32u服务器启动以来存储过的内容总数

bytes 64u服务器当前存储内容所占用的字节数

curr_connections 32u连接数量

total_connections32u服务器运行以来接受的连接总数

connection_structures32u服务器分配的连接结构的数量

cmd_get 64u取回请求总数

cmd_set 64u存储请求总数

get_hits 64u请求成功的总次数

get_misses 64u请求失败的总次数

evictions 64u为更新项目将有效的项目从缓存释放的次数

bytes_read 64u服务器从网络读取到的总字节数

bytes_written 64u服务器向网络发送的总字节数

limit_maxbytes 32u服务器在存储时被允许使用的字节总数

threads 32u所需工作线程数

其它命令

“flush_all”命令有一个可选的数字参数。它总是执行成功，服务器会发送“OK\r\n”回应。它的效果是使已经存在的项目立即失效（缺省），或在指定的时间后。此后执行取回命令，将不会有任何内容返回（除非重新存储同样的键名）。flush_all实际上没有立即释放项目所占用的内存，而是在随后陆续有新的项目被储存时执行。flush_all效果具体如下：它导致所有更新时间早于flush_all所执行时间的项目，不响应取回命令。

“version”命令没有参数：

version\r\n

在回应中，服务器发送：

“VERSION<version>\r\n”

<version>是服务器的版本字串。

“quit”命令没有参数：

quit\r\n

接收此命令后，服务器关闭连接。不过，客户端可以在不再需要时，简单地关闭连接就行，并不一定需要发送这个命令。