memcached 数据交换协议
转载：http://code.sixapart.com/svn/memcached/trunk/server/doc/protocol.txtProtocol--------Clients of memcached communicate with server through TCP connections.(A UDP interface is also available; details are below under "UDPprotocol.") A given running memcached server listens on some(configurable) port; clients connect to that port, send commands tothe server, read responses, and eventually close the connection.There is no need to send any command to end the session. A client mayjust close the connection at any moment it no longer needs it. Note,however, that clients are encouraged to cache their connections ratherthan reopen them every time they need to store or retrieve data.Thisis because memcached is especially designed to work very efficientlywith a very large number (many hundreds, more than a thousand ifnecessary) of open connections. Caching connections will eliminate theoverhead associated with establishing a TCP connection (the overheadof preparing for a new connection on the server side is insignificantcompared to this).There are two kinds of data sent in the memcache protocol: text linesand unstructured data.Text lines are used for commands from clientsand responses from servers. Unstructured data is sent when a clientwants to store or retrieve data. The server will transmit backunstructured data in exactly the same way it received it, as a bytestream. The server doesn't care about byte order issues inunstructured data and isn't aware of them. There are no limitations oncharacters that may appear in unstructured data; however, the readerof such data (either a client or a server) will always know, from apreceding text line, the exact length of the data block beingtransmitted.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 charactersmay also appear inside the data. Therefore, when a client retrievesdata from a server, it must use the length of the data block (which itwill be provided with) to determine where the data block ends, and notthe fact that \r\n follows the end of the data block, even though itdoes.Keys----Data stored by memcached is identified with the help of a key. A keyis a text string which should uniquely identify the data for clientsthat are interested in storing and retrieving it.Currently thelength limit of a key is set at 250 characters (of course, normallyclients wouldn't need to use such long keys); the key must not includecontrol characters or whitespace.Commands--------There are three types of commands. Storage commands (there are three: "set", "add" and "replace") ask theserver to store some data identified by a key. The client sends acommand line, and then a data block; after that the client expects oneline of response, which will indicate success or faulure.Retrieval commands (there is only one: "get") ask the server toretrieve data corresponding to a set of keys (one or more keys in onerequest). The client sends a command line, which includes all therequested keys; after that for each item the server finds it sends tothe client one response line with information about the item, and onedata block with the item's data; this continues until the serverfinished 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 thecommand) either one line of response, or several lines of responseending with "END" on the last line.A command line always starts with the name of the command, followed byparameters (if any) delimited by whitespace. Command names arelower-case and are case-sensitive.Expiration times----------------Some commands involve a client sending some kind of expiration time(relative to an item or to an operation requested by the client) tothe server. In all such cases, the actual value sent may either beUnix time (number of seconds since January 1, 1970, as a 32-bitvalue), or a number of seconds starting from current time. In thelatter case, this number of seconds may not exceed 60*60*24*30 (numberof seconds in 30 days); if the number sent by a client is larger thanthat, the server will consider it to be real Unix time value ratherthan an offset from current time.Error strings-------------Each command sent by a client may be answered with an error stringfrom 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 inputdoesn't conform to the protocol in some way. <error> is ahuman-readable error string.- "SERVER_ERROR <error>\r\n"means some sort of server error prevents the server from carryingout the command. <error> is a human-readable error string. In casesof severe server errors, which make it impossible to continueserving the client (this shouldn't normally happen), the server willclose the connection after sending the error line. This is the onlycase in which the server closes a connection to a client.In the descriptions of individual commands below, these error linesare not again specifically mentioned, but clients must allow for theirpossibility.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* alreadyhold 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 indecimal) that the server stores along with the data and sends backwhen the item is retrieved. Clients may use this as a bit field tostore data-specific information; this field is opaque to the server.Note that in memcached 1.2.1 and higher, flags may be 32-bits, insteadof 16, but you might want to restrict yourself to 16 bits forcompatibility with older versions.- <exptime> is expiration time. If it's 0, the item never expires(although it may be deleted from the cache to make place for otheritems). If it's non-zero (either Unix time or offset in seconds fromcurrent time), it is guaranteed that clients will not be able toretrieve this item after the expiration time arrives (measured byserver 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 caseit'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 awaitsthe reply, which may be:- "STORED\r\n", to indicate success.- "NOT_STORED\r\n" to indicate the data was not stored, but notbecause of an error. This normally means that either that thecondition for an "add" or a "replace" command wasn't met, or that theitem 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 ofwhich is received as a text line followed by a data block. After allthe 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* includingits delimiting \r\n- <data block> is the data for this item.If some of the keys appearing in a retrieval request are not sent backby the server in the item list this means that the server does nothold items with such keys (because they were never stored, or storedbut deleted to make space for more items, or expired, or explicitlydeleted 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" commandswith this key. For this amount of item, the item is put into adelete queue, which means that it won't possible to retrieve it bythe "get" command, but "add" and "replace" command with this keywill also fail (the "set" command will succeed, however). After thetime 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 furtherstorage 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 notfound.See the "flush_all" command below for immediate invalidationof all existing items.Increment/Decrement-------------------Commands "incr" and "decr" are used to change data for some itemin-place, incrementing or decrementing it. The data for the item istreated as decimal representation of a 32-bit unsigned integer. If thecurrent data value does not conform to such a representation, thecommands behave as if the value were 0. Also, the item must alreadyexist for incr/decr to work; these commands won't pretend that anon-existent key exists with value 0; instead, they will fail.The client sends the command line:incr <key> <value>\r\nordecr <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/decreasethe 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 triesto decrease the value below 0, the new value will be 0.Overflow in the"incr" command will wrap around the 32 bit mark.Note also that decrementing a number such that it loses length isn'tguaranteed to decrement its returned length.The number MAY bespace-padded at the end, but this is purely an implementationoptimization, so you also shouldn't rely on that.Statistics----------The command "stats" is used to query the server about statistics itmaintains and other internal data. It has two forms. Withoutarguments:stats\r\nit causes the server to output general-purpose statistics andsettings, documented below.In the other form it has some arguments:stats <args>\r\nDepending on <args>, various internal data is sent by the server. Thekinds of arguments and the data sent are not documented in this vesionof the protocol, and are subject to change for the convenience ofmemcache developers.General-purpose statistics--------------------------Upon receiving the "stats" command without arguments, the server sentsa number of lines which look like this:STAT <name> <value>\r\nThe server terminates this list with the lineEND\r\nIn 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 inresponse to the "stats" command, together with the type of the valuesent 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 unsignedintegers separated by a colon.Name Type Meaning----------------------------------pid 32u Process id of this server processuptime 32u Number of seconds this server has been runningtime 32u current UNIX time according to the serverversion string Version string of this serverpointer_size 32 Default size of pointers on the host OS (generally 32 or 64)rusage_user 32u:32uAccumulated user time for this process (seconds:microseconds)rusage_system 32u:32uAccumulated system time for this process (seconds:microseconds)curr_items 32u Current number of items stored by the servertotal_items 32u Total number of items stored by this server ever since it startedbytes 64u Current number of bytes used by this server to store itemscurr_connections32u Number of open connectionstotal_connections 32u Total number of connections opened since the server started runningconnection_structures 32uNumber of connection structures allocated by the servercmd_get 64u Cumulative number of retrieval requestscmd_set 64u Cumulative number of storage requestsget_hits 64u Number of keys that have been requested and found presentget_misses 64u Number of items that have been requested and not foundevictions 64u Number of valid items removed from cache to free memory for new items bytes_read 64u Total number of bytes read by this server from networkbytes_written 64u Total number of bytes sent by this server to networklimit_maxbytes 32u Number of bytes this server is allowed to use for storage. threads 32u Number of worker threads requested. (see doc/threads.txt)Other commands--------------"flush_all" is a command with an optional numeric argument. It alwayssucceeds, and the server sends "OK\r\n" in response. Its effect is toinvalidate all existing items immediately (by default) or after theexpiration specified.After invalidation none of the items will be returnedin response to a retrieval command (unless it's stored again under thesame key *after* flush_all has invalidated the items). flush_all doesn'tactually free all the memory taken up by existing items; that willhappen gradually as new items are stored. The most precise definitionof what flush_all does is the following: it causes all items whoseupdate time is earlier than the time at which flush_all was set to beexecuted to be ignored for retrieval purposes.The intent of flush_all with a delay, was that in a setting where youhave a pool of memcached servers, and you need to flush all content,you have the option of not resetting all memcached servers at thesame time (which could e.g. cause a spike in database load with allclients suddenly needing to recreate content that would otherwisehave been found in the memcached daemon).The delay option allows you to have them reset in e.g. 10 secondintervals (by passing 0 to the first, 10 to the second, 20 to thethird, etc. etc.)."version" is a command with no arguments:version\r\nIn response, the server sends"VERSION <version>\r\n", where <version> is the version string for theserver."verbosity" is a command with a numeric argument. It always succeeds, and the server sends "OK\r\n" in response. Its effect is to set the verbosity level of the logging output. "quit" is a command with no arguments:quit\r\nUpon receiving this command, the server closes theconnection. However, the client may also simply close the connectionwhen it no longer needs it, without issuing this command.UDP protocol------------For very large installations where the number of clients is high enoughthat the number of TCP connections causes scaling difficulties, there isalso a UDP-based interface. The UDP interface does not provide guaranteeddelivery, so should only be used for operations that aren't required tosucceed; typically it is used for "get" requests where a missing orincomplete response can simply be treated as a cache miss.Each UDP datagram contains a simple frame header, followed by data in thesame format as the TCP protocol described above. In the currentimplementation, requests must be contained in a single UDP datagram, butresponses may span several datagrams. (The only common requests that wouldspan multiple datagrams are huge multi-key "get" requests and "set"requests, both of which are more suitable to TCP transport for reliabilityreasons anyway.)The frame header is 8 bytes long, as follows (all values are 16-bit integersin network byte order, high byte first):0-1 Request ID2-3 Sequence number4-5 Total number of datagrams in this message6-7 Reserved for future use; must be 0The request ID is supplied by the client. Typically it will be amonotonically increasing value starting from a random seed, but the clientis free to use whatever request IDs it likes. The server's response willcontain the same ID as the incoming request. The client uses the request IDto differentiate between responses to outstanding requests if there areseveral pending from the same server; any datagrams with an unknown requestID are probably delayed responses to an earlier request and should bediscarded.The sequence number ranges from 0 to n-1, where n is the total number ofdatagrams in the message. The client should concatenate the payloads of thedatagrams for a given response in sequence number order; the resulting bytestream will contain a complete response in the same format as the TCPprotocol (including terminating \r\n sequences).
页:
[1]