4 Clients of memcached communicate with server through TCP connections.
5 (A UDP interface is also available; details are below under "UDP
6 protocol.") A given running memcached server listens on some
7 (configurable) port; clients connect to that port, send commands to
8 the server, read responses, and eventually close the connection.
10 There is no need to send any command to end the session. A client may
11 just close the connection at any moment it no longer needs it. Note,
12 however, that clients are encouraged to cache their connections rather
13 than reopen them every time they need to store or retrieve data. This
14 is because memcached is especially designed to work very efficiently
15 with a very large number (many hundreds, more than a thousand if
16 necessary) of open connections. Caching connections will eliminate the
17 overhead associated with establishing a TCP connection (the overhead
18 of preparing for a new connection on the server side is insignificant
21 There are two kinds of data sent in the memcache protocol: text lines
22 and unstructured data. Text lines are used for commands from clients
23 and responses from servers. Unstructured data is sent when a client
24 wants to store or retrieve data. The server will transmit back
25 unstructured data in exactly the same way it received it, as a byte
26 stream. The server doesn't care about byte order issues in
27 unstructured data and isn't aware of them. There are no limitations on
28 characters that may appear in unstructured data; however, the reader
29 of such data (either a client or a server) will always know, from a
30 preceding text line, the exact length of the data block being
33 Text lines are always terminated by \r\n. Unstructured data is _also_
34 terminated by \r\n, even though \r, \n or any other 8-bit characters
35 may also appear inside the data. Therefore, when a client retrieves
36 data from a server, it must use the length of the data block (which it
37 will be provided with) to determine where the data block ends, and not
38 the fact that \r\n follows the end of the data block, even though it
44 Data stored by memcached is identified with the help of a key. A key
45 is a text string which should uniquely identify the data for clients
46 that are interested in storing and retrieving it. Currently the
47 length limit of a key is set at 250 characters (of course, normally
48 clients wouldn't need to use such long keys); the key must not include
49 control characters or whitespace.
54 There are three types of commands.
56 Storage commands (there are six: "set", "add", "replace", "append"
57 "prepend" and "cas") ask the server to store some data identified by a
58 key. The client sends a command line, and then a data block; after
59 that the client expects one line of response, which will indicate
62 Retrieval commands (there are two: "get" and "gets") ask the server to
63 retrieve data corresponding to a set of keys (one or more keys in one
64 request). The client sends a command line, which includes all the
65 requested keys; after that for each item the server finds it sends to
66 the client one response line with information about the item, and one
67 data block with the item's data; this continues until the server
68 finished with the "END" response line.
70 All other commands don't involve unstructured data. In all of them,
71 the client sends one command line, and expects (depending on the
72 command) either one line of response, or several lines of response
73 ending with "END" on the last line.
75 A command line always starts with the name of the command, followed by
76 parameters (if any) delimited by whitespace. Command names are
77 lower-case and are case-sensitive.
82 Some commands involve a client sending some kind of expiration time
83 (relative to an item or to an operation requested by the client) to
84 the server. In all such cases, the actual value sent may either be
85 Unix time (number of seconds since January 1, 1970, as a 32-bit
86 value), or a number of seconds starting from current time. In the
87 latter case, this number of seconds may not exceed 60*60*24*30 (number
88 of seconds in 30 days); if the number sent by a client is larger than
89 that, the server will consider it to be real Unix time value rather
90 than an offset from current time.
96 Each command sent by a client may be answered with an error string
97 from the server. These error strings come in three types:
101 means the client sent a nonexistent command name.
103 - "CLIENT_ERROR <error>\r\n"
105 means some sort of client error in the input line, i.e. the input
106 doesn't conform to the protocol in some way. <error> is a
107 human-readable error string.
109 - "SERVER_ERROR <error>\r\n"
111 means some sort of server error prevents the server from carrying
112 out the command. <error> is a human-readable error string. In cases
113 of severe server errors, which make it impossible to continue
114 serving the client (this shouldn't normally happen), the server will
115 close the connection after sending the error line. This is the only
116 case in which the server closes a connection to a client.
119 In the descriptions of individual commands below, these error lines
120 are not again specifically mentioned, but clients must allow for their
127 First, the client sends a command line which looks like this:
129 <command name> <key> <flags> <exptime> <bytes> [noreply]\r\n
130 cas <key> <flags> <exptime> <bytes> <cas unique> [noreply]\r\n
132 - <command name> is "set", "add", "replace", "append" or "prepend"
134 "set" means "store this data".
136 "add" means "store this data, but only if the server *doesn't* already
137 hold data for this key".
139 "replace" means "store this data, but only if the server *does*
140 already hold data for this key".
142 "append" means "add this data to an existing key after existing data".
144 "prepend" means "add this data to an existing key before existing data".
146 The append and prepend commands do not accept flags or exptime.
147 They update existing data portions, and ignore new flag and exptime
150 "cas" is a check and set operation which means "store this data but
151 only if no one else has updated since I last fetched it."
153 - <key> is the key under which the client asks to store the data
155 - <flags> is an arbitrary 16-bit unsigned integer (written out in
156 decimal) that the server stores along with the data and sends back
157 when the item is retrieved. Clients may use this as a bit field to
158 store data-specific information; this field is opaque to the server.
159 Note that in memcached 1.2.1 and higher, flags may be 32-bits, instead
160 of 16, but you might want to restrict yourself to 16 bits for
161 compatibility with older versions.
163 - <exptime> is expiration time. If it's 0, the item never expires
164 (although it may be deleted from the cache to make place for other
165 items). If it's non-zero (either Unix time or offset in seconds from
166 current time), it is guaranteed that clients will not be able to
167 retrieve this item after the expiration time arrives (measured by
170 - <bytes> is the number of bytes in the data block to follow, *not*
171 including the delimiting \r\n. <bytes> may be zero (in which case
172 it's followed by an empty data block).
174 - <cas unique> is a unique 64-bit value of an existing entry.
175 Clients should use the value returned from the "gets" command
176 when issuing "cas" updates.
178 - "noreply" optional parameter instructs the server to not send the
179 reply. NOTE: if the request line is malformed, the server can't
180 parse "noreply" option reliably. In this case it may send the error
181 to the client, and not reading it on the client side will break
182 things. Client should construct only valid requests.
184 After this line, the client sends the data block:
188 - <data block> is a chunk of arbitrary 8-bit data of length <bytes>
189 from the previous line.
191 After sending the command line and the data blockm the client awaits
192 the reply, which may be:
194 - "STORED\r\n", to indicate success.
196 - "NOT_STORED\r\n" to indicate the data was not stored, but not
197 because of an error. This normally means that the
198 condition for an "add" or a "replace" command wasn't met.
200 - "EXISTS\r\n" to indicate that the item you are trying to store with
201 a "cas" command has been modified since you last fetched it.
203 - "NOT_FOUND\r\n" to indicate that the item you are trying to store
204 with a "cas" command did not exist.
210 The retrieval commands "get" and "gets" operates like this:
215 - <key>* means one or more key strings separated by whitespace.
217 After this command, the client expects zero or more items, each of
218 which is received as a text line followed by a data block. After all
219 the items have been transmitted, the server sends the string
223 to indicate the end of response.
225 Each item sent by the server looks like this:
227 VALUE <key> <flags> <bytes> [<cas unique>]\r\n
230 - <key> is the key for the item being sent
232 - <flags> is the flags value set by the storage command
234 - <bytes> is the length of the data block to follow, *not* including
237 - <cas unique> is a unique 64-bit integer that uniquely identifies
240 - <data block> is the data for this item.
242 If some of the keys appearing in a retrieval request are not sent back
243 by the server in the item list this means that the server does not
244 hold items with such keys (because they were never stored, or stored
245 but deleted to make space for more items, or expired, or explicitly
246 deleted by a client).
252 The command "delete" allows for explicit deletion of items:
254 delete <key> [noreply]\r\n
256 - <key> is the key of the item the client wishes the server to delete
258 - "noreply" optional parameter instructs the server to not send the
259 reply. See the note in Storage commands regarding malformed
262 The response line to this command can be one of:
264 - "DELETED\r\n" to indicate success
266 - "NOT_FOUND\r\n" to indicate that the item with this key was not
269 See the "flush_all" command below for immediate invalidation
270 of all existing items.
276 Commands "incr" and "decr" are used to change data for some item
277 in-place, incrementing or decrementing it. The data for the item is
278 treated as decimal representation of a 64-bit unsigned integer. If
279 the current data value does not conform to such a representation, the
280 incr/decr commands return an error (memcached <= 1.2.6 treated the
281 bogus value as if it were 0, leading to confusing). Also, the item
282 must already exist for incr/decr to work; these commands won't pretend
283 that a non-existent key exists with value 0; instead, they will fail.
285 The client sends the command line:
287 incr <key> <value> [noreply]\r\n
291 decr <key> <value> [noreply]\r\n
293 - <key> is the key of the item the client wishes to change
295 - <value> is the amount by which the client wants to increase/decrease
296 the item. It is a decimal representation of a 64-bit unsigned integer.
298 - "noreply" optional parameter instructs the server to not send the
299 reply. See the note in Storage commands regarding malformed
302 The response will be one of:
304 - "NOT_FOUND\r\n" to indicate the item with this value was not found
306 - <value>\r\n , where <value> is the new value of the item's data,
307 after the increment/decrement operation was carried out.
309 Note that underflow in the "decr" command is caught: if a client tries
310 to decrease the value below 0, the new value will be 0. Overflow in
311 the "incr" command will wrap around the 64 bit mark.
313 Note also that decrementing a number such that it loses length isn't
314 guaranteed to decrement its returned length. The number MAY be
315 space-padded at the end, but this is purely an implementation
316 optimization, so you also shouldn't rely on that.
321 The "touch" command is used to update the expiration time of an existing item
324 touch <key> <exptime> [noreply]\r\n
326 - <key> is the key of the item the client wishes the server to delete
328 - <exptime> is expiration time. Works the same as with the update commands
329 (set/add/etc). This replaces the existing expiration time. If an existing
330 item were to expire in 10 seconds, but then was touched with an
331 expiration time of "20", the item would then expire in 20 seconds.
333 - "noreply" optional parameter instructs the server to not send the
334 reply. See the note in Storage commands regarding malformed
337 The response line to this command can be one of:
339 - "TOUCHED\r\n" to indicate success
341 - "NOT_FOUND\r\n" to indicate that the item with this key was not
347 NOTE: This command is subject to change as of this writing.
349 The slabs reassign command is used to redistribute memory once a running
350 instance has hit its limit. It might be desireable to have memory laid out
351 differently than was automatically assigned after the server started.
353 slabs reassign <source class> <dest class>\r\n
355 - <source class> is an id number for the slab class to steal a page from
357 A source class id of -1 means "pick from any valid class"
359 - <dest class> is an id number for the slab class to move a page to
361 The response line could be one of:
363 - "OK" to indicate the page has been scheduled to move
365 - "BUSY [message]" to indicate a page is already being processed, try again
368 - "BADCLASS [message]" a bad class id was specified
370 - "NOSPARE [message]" source class has no spare pages
372 - "NOTFULL [message]" dest class must be full to move new pages to it
374 - "UNSAFE [message]" source class cannot move a page right now
376 - "SAME [message]" must specify different source/dest ids.
381 NOTE: This command is subject to change as of this writing.
383 The slabs automove command enables a background thread which decides on its
384 own when to move memory between slab classes. Its implementation and options
385 will likely be in flux for several versions. See the wiki/mailing list for
388 The automover can be enabled or disabled at runtime with this command.
392 - 0|1|2 is the indicator on whether to enable the slabs automover or not.
394 The response should always be "OK\r\n"
396 - <0> means to set the thread on standby
398 - <1> means to run the builtin slow algorithm to choose pages to move
400 - <2> is a highly aggressive mode which causes pages to be moved every time
401 there is an eviction. It is not recommended to run for very long in this
402 mode unless your access patterns are very well understood.
407 The command "stats" is used to query the server about statistics it
408 maintains and other internal data. It has two forms. Without
413 it causes the server to output general-purpose statistics and
414 settings, documented below. In the other form it has some arguments:
418 Depending on <args>, various internal data is sent by the server. The
419 kinds of arguments and the data sent are not documented in this version
420 of the protocol, and are subject to change for the convenience of
424 General-purpose statistics
425 --------------------------
427 Upon receiving the "stats" command without arguments, the server sents
428 a number of lines which look like this:
430 STAT <name> <value>\r\n
432 The server terminates this list with the line
436 In each line of statistics, <name> is the name of this statistic, and
437 <value> is the data. The following is the list of all names sent in
438 response to the "stats" command, together with the type of the value
439 sent for this name, and the meaning of the value.
441 In the type column below, "32u" means a 32-bit unsigned integer, "64u"
442 means a 64-bit unsigned integer. '32u.32u' means two 32-bit unsigned
443 integers separated by a colon (treat this as a floating point number).
445 |-----------------------+---------+-------------------------------------------|
446 | Name | Type | Meaning |
447 |-----------------------+---------+-------------------------------------------|
448 | pid | 32u | Process id of this server process |
449 | uptime | 32u | Number of secs since the server started |
450 | time | 32u | current UNIX time according to the server |
451 | version | string | Version string of this server |
452 | pointer_size | 32 | Default size of pointers on the host OS |
453 | | | (generally 32 or 64) |
454 | rusage_user | 32u.32u | Accumulated user time for this process |
455 | | | (seconds:microseconds) |
456 | rusage_system | 32u.32u | Accumulated system time for this process |
457 | | | (seconds:microseconds) |
458 | curr_items | 32u | Current number of items stored |
459 | total_items | 32u | Total number of items stored since |
460 | | | the server started |
461 | bytes | 64u | Current number of bytes used |
462 | | | to store items |
463 | curr_connections | 32u | Number of open connections |
464 | total_connections | 32u | Total number of connections opened since |
465 | | | the server started running |
466 | connection_structures | 32u | Number of connection structures allocated |
467 | | | by the server |
468 | reserved_fds | 32u | Number of misc fds used internally |
469 | cmd_get | 64u | Cumulative number of retrieval reqs |
470 | cmd_set | 64u | Cumulative number of storage reqs |
471 | cmd_flush | 64u | Cumulative number of flush reqs |
472 | cmd_touch | 64u | Cumulative number of touch reqs |
473 | get_hits | 64u | Number of keys that have been requested |
474 | | | and found present |
475 | get_misses | 64u | Number of items that have been requested |
476 | | | and not found |
477 | delete_misses | 64u | Number of deletions reqs for missing keys |
478 | delete_hits | 64u | Number of deletion reqs resulting in |
479 | | | an item being removed. |
480 | incr_misses | 64u | Number of incr reqs against missing keys. |
481 | incr_hits | 64u | Number of successful incr reqs. |
482 | decr_misses | 64u | Number of decr reqs against missing keys. |
483 | decr_hits | 64u | Number of successful decr reqs. |
484 | cas_misses | 64u | Number of CAS reqs against missing keys. |
485 | cas_hits | 64u | Number of successful CAS reqs. |
486 | cas_badval | 64u | Number of CAS reqs for which a key was |
487 | | | found, but the CAS value did not match. |
488 | touch_hits | 64u | Numer of keys that have been touched with |
489 | | | a new expiration time |
490 | touch_misses | 64u | Numer of items that have been touched and |
492 | auth_cmds | 64u | Number of authentication commands |
493 | | | handled, success or failure. |
494 | auth_errors | 64u | Number of failed authentications. |
495 | evictions | 64u | Number of valid items removed from cache |
496 | | | to free memory for new items |
497 | reclaimed | 64u | Number of times an entry was stored using |
498 | | | memory from an expired entry |
499 | bytes_read | 64u | Total number of bytes read by this server |
501 | bytes_written | 64u | Total number of bytes sent by this server |
503 | limit_maxbytes | 32u | Number of bytes this server is allowed to |
504 | | | use for storage. |
505 | threads | 32u | Number of worker threads requested. |
506 | | | (see doc/threads.txt) |
507 | conn_yields | 64u | Number of times any connection yielded to |
508 | | | another due to hitting the -R limit. |
509 | hash_power_level | 32u | Current size multiplier for hash table |
510 | hash_bytes | 64u | Bytes currently used by hash tables |
511 | hash_is_expanding | bool | Indicates if the hash table is being |
512 | | | grown to a new size |
513 | expired_unfetched | 64u | Items pulled from LRU that were never |
514 | | | touched by get/incr/append/etc before |
516 | evicted_unfetched | 64u | Items evicted from LRU that were never |
517 | | | touched by get/incr/append/etc. |
518 | slab_reassign_running | bool | If a slab page is being moved |
519 | slabs_moved | 64u | Total slab pages moved |
520 |-----------------------+---------+-------------------------------------------|
524 CAVEAT: This section describes statistics which are subject to change in the
527 The "stats" command with the argument of "settings" returns details of
528 the settings of the running memcached. This is primarily made up of
529 the results of processing commandline options.
531 Note that these are not guaranteed to return in any specific order and
532 this list may not be exhaustive. Otherwise, this returns like any
535 |-------------------+----------+----------------------------------------------|
536 | Name | Type | Meaning |
537 |-------------------+----------+----------------------------------------------|
538 | maxbytes | size_t | Maximum number of bytes allows in this cache |
539 | maxconns | 32 | Maximum number of clients allowed. |
540 | tcpport | 32 | TCP listen port. |
541 | udpport | 32 | UDP listen port. |
542 | inter | string | Listen interface. |
543 | verbosity | 32 | 0 = none, 1 = some, 2 = lots |
544 | oldest | 32u | Age of the oldest honored object. |
545 | evictions | on/off | When off, LRU evictions are disabled. |
546 | domain_socket | string | Path to the domain socket (if any). |
547 | umask | 32 (oct) | umask for the creation of the domain socket. |
548 | growth_factor | float | Chunk size growth factor. |
549 | chunk_size | 32 | Minimum space allocated for key+value+flags. |
550 | num_threads | 32 | Number of threads (including dispatch). |
551 | stat_key_prefix | char | Stats prefix separator character. |
552 | detail_enabled | bool | If yes, stats detail is enabled. |
553 | reqs_per_event | 32 | Max num IO ops processed within an event. |
554 | cas_enabled | bool | When no, CAS is not enabled for this server. |
555 | tcp_backlog | 32 | TCP listen backlog. |
556 | auth_enabled_sasl | yes/no | SASL auth requested and enabled. |
557 | item_size_max | size_t | maximum item size |
558 | maxconns_fast | bool | If fast disconnects are enabled |
559 | hashpower_init | 32 | Starting size multiplier for hash table |
560 | slab_reassign | bool | Whether slab page reassignment is allowed |
561 | slab_automove | bool | Whether slab page automover is enabled |
562 |-------------------+----------+----------------------------------------------|
567 CAVEAT: This section describes statistics which are subject to change in the
570 The "stats" command with the argument of "items" returns information about
571 item storage per slab class. The data is returned in the format:
573 STAT items:<slabclass>:<stat> <value>\r\n
575 The server terminates this list with the line
579 The slabclass aligns with class ids used by the "stats slabs" command. Where
580 "stats slabs" describes size and memory usage, "stats items" shows higher
583 The following item values are defined as of writing.
586 ------------------------------
587 number Number of items presently stored in this class. Expired
588 items are not automatically excluded.
589 age Age of the oldest item in the LRU.
590 evicted Number of times an item had to be evicted from the LRU
592 evicted_nonzero Number of times an item which had an explicit expire
593 time set had to be evicted from the LRU before it
595 evicted_time Seconds since the last access for the most recent item
596 evicted from this class. Use this to judge how
597 recently active your evicted data is.
598 outofmemory Number of times the underlying slab class was unable to
599 store a new item. This means you are running with -M or
601 tailrepairs Number of times we self-healed a slab with a refcount
602 leak. If this counter is increasing a lot, please
603 report your situation to the developers.
604 reclaimed Number of times an entry was stored using memory from
606 expired_unfetched Number of expired items reclaimed from the LRU which
607 were never touched after being set.
608 evicted_unfetched Number of valid items evicted from the LRU which were
609 never touched after being set.
611 Note this will only display information about slabs which exist, so an empty
612 cache will return an empty set.
617 CAVEAT: This section describes statistics which are subject to change in the
620 The "stats" command with the argument of "sizes" returns information about the
621 general size and count of all items stored in the cache.
622 WARNING: This command WILL lock up your cache! It iterates over *every item*
623 and examines the size. While the operation is fast, if you have many items
624 you could prevent memcached from serving requests for several seconds.
626 The data is returned in the following format:
630 The server terminates this list with the line
634 'size' is an approximate size of the item, within 32 bytes.
635 'count' is the amount of items that exist within that 32-byte range.
637 This is essentially a display of all of your items if there was a slab class
638 for every 32 bytes. You can use this to determine if adjusting the slab growth
639 factor would save memory overhead. For example: generating more classes in the
640 lower range could allow items to fit more snugly into their slab classes, if
641 most of your items are less than 200 bytes in size.
646 CAVEAT: This section describes statistics which are subject to change in the
649 The "stats" command with the argument of "slabs" returns information about
650 each of the slabs created by memcached during runtime. This includes per-slab
651 information along with some totals. The data is returned in the format:
653 STAT <slabclass>:<stat> <value>\r\n
654 STAT <stat> <value>\r\n
656 The server terminates this list with the line
660 |-----------------+----------------------------------------------------------|
662 |-----------------+----------------------------------------------------------|
663 | chunk_size | The amount of space each chunk uses. One item will use |
664 | | one chunk of the appropriate size. |
665 | chunks_per_page | How many chunks exist within one page. A page by |
666 | | default is less than or equal to one megabyte in size. |
667 | | Slabs are allocated by page, then broken into chunks. |
668 | total_pages | Total number of pages allocated to the slab class. |
669 | total_chunks | Total number of chunks allocated to the slab class. |
670 | get_hits | Total number of get requests serviced by this class. |
671 | cmd_set | Total number of set requests storing data in this class. |
672 | delete_hits | Total number of successful deletes from this class. |
673 | incr_hits | Total number of incrs modifying this class. |
674 | decr_hits | Total number of decrs modifying this class. |
675 | cas_hits | Total number of CAS commands modifying this class. |
676 | cas_badval | Total number of CAS commands that failed to modify a |
677 | | value due to a bad CAS id. |
678 | touch_hits | Total number of touches serviced by this class. |
679 | used_chunks | How many chunks have been allocated to items. |
680 | free_chunks | Chunks not yet allocated to items, or freed via delete. |
681 | free_chunks_end | Number of free chunks at the end of the last allocated |
683 | mem_requested | Number of bytes requested to be stored in this slab[*]. |
684 | active_slabs | Total number of slab classes allocated. |
685 | total_malloced | Total amount of memory allocated to slab pages. |
686 |-----------------+----------------------------------------------------------|
688 * Items are stored in a slab that is the same size or larger than the
689 item. mem_requested shows the size of all items within a
690 slab. (total_chunks * chunk_size) - mem_requested shows memory
691 wasted in a slab class. If you see a lot of waste, consider tuning
697 "flush_all" is a command with an optional numeric argument. It always
698 succeeds, and the server sends "OK\r\n" in response (unless "noreply"
699 is given as the last parameter). Its effect is to invalidate all
700 existing items immediately (by default) or after the expiration
701 specified. After invalidation none of the items will be returned in
702 response to a retrieval command (unless it's stored again under the
703 same key *after* flush_all has invalidated the items). flush_all
704 doesn't actually free all the memory taken up by existing items; that
705 will happen gradually as new items are stored. The most precise
706 definition of what flush_all does is the following: it causes all
707 items whose update time is earlier than the time at which flush_all
708 was set to be executed to be ignored for retrieval purposes.
710 The intent of flush_all with a delay, was that in a setting where you
711 have a pool of memcached servers, and you need to flush all content,
712 you have the option of not resetting all memcached servers at the
713 same time (which could e.g. cause a spike in database load with all
714 clients suddenly needing to recreate content that would otherwise
715 have been found in the memcached daemon).
717 The delay option allows you to have them reset in e.g. 10 second
718 intervals (by passing 0 to the first, 10 to the second, 20 to the
722 "version" is a command with no arguments:
726 In response, the server sends
728 "VERSION <version>\r\n", where <version> is the version string for the
731 "verbosity" is a command with a numeric argument. It always succeeds,
732 and the server sends "OK\r\n" in response (unless "noreply" is given
733 as the last parameter). Its effect is to set the verbosity level of
736 "quit" is a command with no arguments:
740 Upon receiving this command, the server closes the
741 connection. However, the client may also simply close the connection
742 when it no longer needs it, without issuing this command.
748 For very large installations where the number of clients is high enough
749 that the number of TCP connections causes scaling difficulties, there is
750 also a UDP-based interface. The UDP interface does not provide guaranteed
751 delivery, so should only be used for operations that aren't required to
752 succeed; typically it is used for "get" requests where a missing or
753 incomplete response can simply be treated as a cache miss.
755 Each UDP datagram contains a simple frame header, followed by data in the
756 same format as the TCP protocol described above. In the current
757 implementation, requests must be contained in a single UDP datagram, but
758 responses may span several datagrams. (The only common requests that would
759 span multiple datagrams are huge multi-key "get" requests and "set"
760 requests, both of which are more suitable to TCP transport for reliability
763 The frame header is 8 bytes long, as follows (all values are 16-bit integers
764 in network byte order, high byte first):
768 4-5 Total number of datagrams in this message
769 6-7 Reserved for future use; must be 0
771 The request ID is supplied by the client. Typically it will be a
772 monotonically increasing value starting from a random seed, but the client
773 is free to use whatever request IDs it likes. The server's response will
774 contain the same ID as the incoming request. The client uses the request ID
775 to differentiate between responses to outstanding requests if there are
776 several pending from the same server; any datagrams with an unknown request
777 ID are probably delayed responses to an earlier request and should be
780 The sequence number ranges from 0 to n-1, where n is the total number of
781 datagrams in the message. The client should concatenate the payloads of the
782 datagrams for a given response in sequence number order; the resulting byte
783 stream will contain a complete response in the same format as the TCP
784 protocol (including terminating \r\n sequences).