123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322 |
- specification:
- - https://github.com/memcached/memcached/blob/master/doc/protocol.txt
- - 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) 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.
- - errors:
- - "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.
- commands:
- - 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.
- - Short list:
- - level 0: basic functionality
- - get
- - set
- - delete
- - flush_all
- - quit
- - level 1: debuggability
- - stats|stats * (some)
- - verbosity
- - version
- - level 2: update functions
- - add|replace
- - append|prepend
- - incr|decr
- - touch
- - stats (related to these functions)
- - level 3: cas
- - cas
- - gets
- - stats (cas-related)
- - level 4: legacy
- - slab_automove|slabs_reassign
- - stats (related to slabs)
- storage:
- - 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 failure.
- - commands:
- - basic commands:
- - "add|replace|set <key> <flags> <exptime> <bytes> [noreply]\r\n"
- - add: store the data under the key, but only if data for the key does not already exist
- - replace: store the data under the key, but only if data for the key already exist
- - set: store the data under the key
- - update commands:
- - "append|prepend <key> <bytes> [noreply]\r\n"
- - append: add this data to an existing key after existing data (?)
- - prepend: add this data to an existing key before existing data (?)
- - cas:
- - "cas <key> <flags> <exptime> <bytes> <cas unique> [noreply]\r\n"
- - check and set operation which means "store this data but only if no one else has updated
- since I last fetched it."
- - command format:
- <key>: 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. Note that in
- memcached 1.2.1 and higher, flags may be 32-bits, instead of 16, but you might want to
- restrict yourself to 16 bits for compatibility 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 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 byserver time).
- - If a negative value is given the item is immediately expired.
- <bytes>:
- - 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).
- <cas unique>:
- - only used by the cas command
- - a unique 64-bit value of an existing entry.
- - Clients should use the value returned from the "gets" command when issuing "cas" updates.
- "noreply":
- - optional parameter instructs the server to not send the reply.
- - NOTE: if the request line is malformed, the server can't parse "noreply" option reliably.
- In this case it may send the error to the client, and not reading it on the client side will
- break things. Client should construct only valid requests.
- data:
- - 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.
- - responses:
- - After sending the command line and the data block 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 the condition for an "add" or a "replace" command wasn't met.
- - "EXISTS\r\n" to indicate that the item you are trying to store with a "cas" command has been
- modified since you last fetched it.
- - "NOT_FOUND\r\n" to indicate that the item you are trying to store with a "cas" command did
- not exist.
- retrieval:
- - 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.
- - commands:
- - "get|gets <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> [<cas unique>]\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
- - <cas unique> is a unique 64-bit integer that uniquely identifies this specific item.
- - <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).
- other:
- - 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.
- - commands:
- - delete:
- - "delete <key> [noreply]\r\n"
- - <key> is the key of the item the client wishes the server to delete
- - "noreply" optional parameter instructs the server to not send the reply.
- - 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.
- - "flush_all [<delay>]\r\n":
- - It always succeeds, and the server sends "OK\r\n" in response (unless "noreply" is given as the last parameter).
- - Its effect is to invalidate all existing items immediately (by default) or after the
- expiration specified in <delay>.
- - 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.
- - The intent of flush_all with a delay, was that in a setting where you have a pool of
- memcached servers, and you need to flush all content, you have the option of not resetting
- all memcached servers at the same time (which could e.g. cause a spike in database load
- with all clients suddenly needing to recreate content that would otherwise have been found
- in the memcached daemon). The delay option allows you to have them reset in e.g. 10 second
- intervals (by passing 0 to the first, 10 to the second, 20 to the third, etc. etc.).
- - increment/decrement:
- - change data for some item in-place, incrementing or decrementing it.
- - "incr|decr <key> <value> [noreply]\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 64-bit unsigned integer.
- - "noreply" optional parameter instructs the server to not send the reply.
- - 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.
- - The data for the item is treated as decimal representation of a 64-bit unsigned integer.
- - If the current data value does not conform to such a representation, the incr/decr commands
- return an error
- - 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.
- - 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 will wrap around the 64 bit mark.
- - 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.
- - "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.
- - slabs automove:
- - "slabs automove <0|1|2>":
- - 0|1|2 is the indicator on whether to enable the slabs automover or not.
- - <0> means to set the thread on standby
- - <1> means to run the builtin slow algorithm to choose pages to move
- - <2> is a highly aggressive mode which causes pages to be moved every time there is an
- eviction. It is not recommended to run for very long in this mode unless your access
- patterns are very well understood.
- - The response should always be "OK\r\n"
- - slabs reassign:
- - distribute memory once a running instance has hit its limit. It might be desireable to have
- memory laid out differently than was automatically assigned after the server started.
- - "slabs reassign <source class> <dest class>\r\n":
- - <source class> is an id number for the slab class to steal a page from.
- - A source class id of -1 means "pick from any valid class"
- - <dest class> is an id number for the slab class to move a page to
- - The response line could be one of:
- - "OK" to indicate the page has been scheduled to move
- - "BUSY [message]" to indicate a page is already being processed, try again later.
- - "BADCLASS [message]" a bad class id was specified
- - "NOSPARE [message]" source class has no spare pages
- - "NOTFULL [message]" dest class must be full to move new pages to it
- - "UNSAFE [message]" source class cannot move a page right now
- - "SAME [message]" must specify different source/dest ids.
- - 1.5.0: "NOTE: This command is subject to change as of this writing."
- - stats:
- - "stats\r\n":
- - it causes the server to output general-purpose statistics and settings, documented below.
- - "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 version of the protocol, and are subject to
- change for the convenience of memcache developers.
- - Upon receiving the "stats" command without arguments, the server sents a number of lines
- which look like this:
- - "STAT <name> <value>\r\n"
- - "<name>" is the name of this statistic,
- - "<value>" is the data.
- - The server terminates this list with the line:
- - "END\r\n"
- - refer to the protocl document for the actual list of values, liable to change on each
- version of memcached.
- - "stats settings\r\n":
- - returns details of the settings of the running memcached. This is primarily made up of
- the results of processing commandline options.
- - these are not guaranteed to return in any specific order and the list in the protocol
- document may not be exhaustive. Otherwise, this returns like any other stats command.
- - "stats items\r\n":
- - Rows look like "STAT items:<slabclass>:<stat> <value>\r\n"
- - <slabclass> aligns with class ids used by the "stats slabs" command. Where "stats slabs"
- describes size and memory usage, "stats items" shows higher level information.
- - <stat> is the name of the statistic being reported by the row
- - <value> is the value of the statistic
- - "stats sizes\r\n":
- - Rows look like "<size> <count>\r\n"
- - <size> is an approximate size of the item, within 32 bytes.
- - <count> is the amount of items that exist within that 32-byte range.
- - May also return "STAT sizes_status disabled"
- - Since 1.4.27, needs to be enabled from the CLI or command "STAT sizes_status disabled"
- which may not work
- - This is essentially a display of all of your items if there was a slab class for every 32
- bytes. You can use this to determine if adjusting the slab growth factor would save memory
- overhead. For example: generating more classes in the lower range could allow items to fit
- more snugly into their slab classes, if most of your items are less than 200 bytes in size.
- - "stats sizes_enable\r\n":
- - enable the histogram at runtime. This has a small overhead to every store or delete
- operation. If you don't want to incur this, leave it off.
- - "stats slabs\r\n" Row may look like:
- - "STAT <slabclass>:<stat> <value>\r\n"
- - <slabclass> aligns with class ids used by the "stats slabs" command.
- - <stat> is the name of the statistic being reported by the row
- - <value> is the value of the statistic
- - "STAT <stat> <value>\r\n"
- - <stat> is the name of the statistic being reported by the row
- - <value> is the value of the statistic
- - touch:
- - update the expiration time of an existing item without fetching it.
- - "touch <key> <exptime> [noreply]\r\n"
- - "<exptime>"
- - Expiration time, same as with the storage commands (set/add/etc).
- - This replaces the existing expiration time. If an existing item were to expire in 10
- seconds, but then was touched with an expiration time of "20", the item would then expire
- in 20 seconds.
- - The response line to this command can be one of:
- - "TOUCHED\r\n" to indicate success
- - "NOT_FOUND\r\n" to indicate that the item with this key was not found.
- - "verbosity <level>\r\n":
- - Always succeeds, and the server sends "OK\r\n" in response (unless "noreply" is given as the
- last parameter). Its effect is to set the verbosity level of the logging output.
- - "version\r\n":
- - Response: "VERSION <version>\r\n"
- - <version> is the version string for the server.
- udp:
- uses:
- - The UDP interface does not provide guaranteed delivery,
- - so should only be used for operations that aren't required to succeed;
- - typically used for "get" requests where a missing or incomplete response can simply be treated as a cache miss.
- format:
- - Each UDP datagram contains a simple frame header, followed by data in the same format as the
- TCP protocol described above.
- - The frame header is 8 bytes long. All values are 16-bit integers in network byte order, high byte first:
- 0-1: Request ID
- - 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.
- 2-3: Sequence number
- - The sequence number ranges from 0 to n-1, where n is the total number of datagrams in the message.
- - The client should concatenate the payloads of the datagrams for a given response in
- sequence number order; the resulting byte stream will contain a complete response in the
- same format as the TCP protocol (including terminating \r\n sequences).
- 4-5: Total number of datagrams in this message
- 6-7: Reserved for future use; must be 0
- - 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.
- versions:
- - Some notable changes... see Changelog for full list
- - 2003 / 1.1.10: added flush_all command
- - 2006 / 1.2.0: added UDP transport
- - 2007 / 1.2.1: <flags> switched from a 16-bit value to a 32-bit value
- - 2007 / 1.2.2: added verbosity command
- - 2007 / 1.2.4:
- - added cas and gets commands
- - incr/decr values switched from 32-bit to 64-bit values
- - 2009 / 1.2.7: increment/decrement no longer treats a non-integer value as 0 but returns an error
- -
|