Using the TCP Text Protocol

When communicating with memcached, you can connect to the server using the port configured for the server. You can open a connection with the server without requiring authorization or login. As soon as you have connected, you can start to send commands to the server. When you have finished, you can terminate the connection without sending any specific disconnection command. Clients are encouraged to keep their connections open to decrease latency and improve performance.

Data is sent to the memcached server in two forms:

• Text lines, which are used to send commands to the server, and receive responses from the server.
• Unstructured data, which is used to receive or send the value information for a given key. Data is returned to the client in exactly the format it was provided.

Both text lines (commands and responses) and unstructured data are always terminated with the string \r\n. Because the data being stored may contain this sequence, the length of the data (returned by the client before the unstructured data is transmitted should be used to determine the end of the data.

Commands to the server are structured according to their operation:

• Storage commands: set, add, replace, append, prepend, cas

  Storage commands to the server take the form:

  command key [flags] [exptime] length [noreply]
  

  Or when using compare and swap (cas):

  cas key [flags] [exptime] length [casunique] [noreply]
  

  Where:

  • command: The command name.
    • set: Store value against key
    • add: Store this value against key if the key does not already exist
    • replace: Store this value against key if the key already exists
    • append: Append the supplied value to the end of the value for the specified key. The flags and exptime arguments should not be used.
    • prepend: Append value currently in the cache to the end of the supplied value for the specified key. The flags and exptime arguments should not be used.
    • cas: Set the specified key to the supplied value, only if the supplied casunique matches. This is effectively the equivalent of change the information if nobody has updated it since I last fetched it.
  • key: The key. All data is stored using a the specific key. The key cannot contain control characters or whitespace, and can be up to 250 characters in size.
  • flags: The flags for the operation (as an integer). Flags in memcached are transparent. The memcached server ignores the contents of the flags. They can be used by the client to indicate any type of information. In memcached 1.2.0 and lower the value is a 16-bit integer value. In memcached 1.2.1 and higher the value is a 32-bit integer.
  • exptime: The expiry time, or zero for no expiry.
  • length: The length of the supplied value block in bytes, excluding the terminating \r\n characters.
  • casunique: A unique 64-bit value of an existing entry. This is used to compare against the existing value. Use the value returned by the gets command when issuing cas updates.
  • noreply: Tells the server not to reply to the command.

  For example, to store the value abcdef into the key xyzkey, you would use:

  set xyzkey 0 0 6\r\nabcdef\r\n
  

  The return value from the server is one line, specifying the status or error information. For more information, see Table 14.2, "memcached Protocol Responses".

• Retrieval commands: get, gets

  Retrieval commands take the form:

  get key1 [key2 .... keyn]
  gets key1 [key2 ... keyn]
  

  You can supply multiple keys to the commands, with each requested key separated by whitespace.

  The server responds with an information line of the form:

  VALUE key flags bytes [casunique]
  

  Where:

  • key: The key name.
  • flags: The value of the flag integer supplied to the memcached server when the value was stored.
  • bytes: The size (excluding the terminating \r\n character sequence) of the stored value.
  • casunique: The unique 64-bit integer that identifies the item.

  The information line is immediately followed by the value data block. For example:

  get xyzkey\r\n VALUE xyzkey 0 6\r\n abcdef\r\n
  

  If you have requested multiple keys, an information line and data block is returned for each key found. If a requested key does not exist in the cache, no information is returned.

• Delete commands: delete

  Deletion commands take the form:

  delete key [time] [noreply]
  

  Where:

  • key: The key name.
  • time: The time in seconds (or a specific Unix time) for which the client wishes the server to refuse add or replace commands on this key. All add, replace, get, and gets commands fail during this period. set operations succeed. After this period, the key is deleted permanently and all commands are accepted.

    If not supplied, the value is assumed to be zero (delete immediately).

  • noreply: Tells the server not to reply to the command.

  Responses to the command are either DELETED to indicate that the key was successfully removed, or NOT_FOUND to indicate that the specified key could not be found.

• Increment/Decrement: incr, decr

  The increment and decrement commands change the value of a key within the server without performing a separate get/set sequence. The operations assume that the currently stored value is a 64-bit integer. If the stored value is not a 64-bit integer, then the value is assumed to be zero before the increment or decrement operation is applied.

  Increment and decrement commands take the form:

  incr key value [noreply]
  decr key value [noreply]
  

  Where:

  • key: The key name.
  • value: An integer to be used as the increment or decrement value.
  • noreply: Tells the server not to reply to the command.

  The response is:

  • NOT_FOUND: The specified key could not be located.
  • value: The new value associated with the specified key.

  Values are assumed to be unsigned. For decr operations, the value is never decremented below 0. For incr operations, the value wraps around the 64-bit maximum.

• Statistics commands: stats

  The stats command provides detailed statistical information about the current status of the memcached instance and the data it is storing.

  Statistics commands take the form:

  STAT [name] [value]
  

  Where:

  • name: The optional name of the statistics to return. If not specified, the general statistics are returned.
  • value: A specific value to be used when performing certain statistics operations.

  The return value is a list of statistics data, formatted as follows:

  STAT name value
  

  The statistics are terminated with a single line, END.

  For more information, see , "Getting memcached Statistics".

For reference, a list of the different commands supported and their formats is provided below.

Table 14.1. memcached Command Reference

Command	Command Formats
set	set key flags exptime length, set key flags exptime length noreply
add	add key flags exptime length, add key flags exptime length noreply
replace	replace key flags exptime length, replace key flags exptime length noreply
append	append key length, append key length noreply
prepend	prepend key length, prepend key length noreply
cas	cas key flags exptime length casunique, cas key flags exptime length casunique noreply
get	get key1 [key2 ... keyn]
gets
delete	delete key, delete key noreply, delete key expiry, delete key expiry noreply
incr	incr key, incr key noreply, incr key value, incr key value noreply
decr	decr key, decr key noreply, decr key value, decr key value noreply
stat	stat, stat name, stat name value

When sending a command to the server, the response from the server is one of the settings in the following table. All response values from the server are terminated by \r\n:

Table 14.2. memcached Protocol Responses

Retornar