The memcache Command Extension

The memcache command extension provides an interface to the memcached memory data caching daemon. This is a useful functionality especially for the implementation of stateful CGI and FCGI applications. This module is now the preferred replacement for the older netcache daemon interface. Current toolkit packages contain both the interface module, and a compiled version of the daemon proper.

The command is thread-safe.

These are the supported subcommands:

memcache append

memcache append mchandle data
memcache append mchandle key data ?ttl_secs? ?flags?

This command is a variant of the memcache put command which appends its data instead of replacing it, if a record already exists for the key. If no such record exists, the command is equivalent to memcache put .

For the explanation of the arguments, please refer to the paragraph on memcache put below.

Example:

memcache append $mch $key $moredata

memcache create

memcache create ?host:port/socketfile?..

Create a new memcached interface object. The command returns a handle of the new object which is used by other memcache commands to identify the object. Multiple interface objects may be used in parallel in an application.

The arguments identify the servers to contact. In case multiple servers are listed, tuples are stored on or retrieved from one of the servers selected in constant but pseudo-random fashion from the key value, resulting in load-balancing.

Servers are identified either by a host name, optionally with an addition custom port number, or the name of a named socket in file system space. An argument is interpreted as a socket name if it contains path separator characters (“/” or “\”), starts with a dot, or starts/ends with a vertical bar “|” or equality sign “=”. If the bar or equality sign are present, it is automatically stripped from the actually used socket name. An attempt is then made to check whether the named socket already exists and can be accessed. If this is not the case, an attempt is made to set it up, and an error results if this operation does not succeed.

Alternatively, servers can be named in the classical hostname:port fashion, where the port part is optional. If no port is specified, the default memcached port 11211 is used. The host name of a server specified here must be resolvable, but at the moment the interface object is created it is not required that a daemon is already listening at the port.

Examples:

set mch [memcache create cachehost1 cachehost2]
set mch [memcache create ./mysocket]

memcache delete

memcache delete all
memcache delete ?mchandle?..

The first command version deletes all active memcache interface objects, after properly closing their connections. The second variant closes and deletes specific handles. The command returns the number of deleted interface objects.

The functionality of the first command variant is automatically executed if the memcache command extension is unloaded.

Deleting an interface handle does not immediately delete the tuples created via this interface on the daemon. The data remains stored until its time-to-live expires, and may be fetched by other interface object instances, even in different processes on different hosts, if they connect to the same daemon and supply the proper keys. To delete tuples, use the memcache remove command.

Deleting an interface handle furthermore does not delete any named sockets associated with the handle, regardless whether these were already present when the object was created, or whether they were automatically set up as a side effect of the object creation.

Example:

memcache delete $mch

memcache get

memcache get mchandle key ?listindex?

Retrieve the data associated with the specified key. The data, which can be binary in nature, is returned as the command result. In case there is no tuple associated with the key, including due to expiration of the lifetime of data associated with the key on the remote daemon, an error results.

If the optional list index is specified, the data is expected to be a properly formed Tcl list. If interpretation as list succeeds, only the selected list element is returned. If the list index is larger than the number of list items in the data, an empty string is the result, but no error is raised.

Example:

set data [memcache get $mch $key]

memcache list

memcache list ?pattern?

Get a list of currently used memcache object handles. If no memcache objects have been created, an empty list is returned. Optionally, a string filter pattern can be specified.

Example:

memcache list

memcache put

memcache put mchandle data
memcache put mchandle key data ?ttl_secs? ?flags?

Store data on a memcache daemon. The data is stored as an opaque byte array and can be of any type. It is not necessary to base64-encode the data or protect it in any other fashion.

The first command variant automatically assigns an unique key and stores the data with it.

The second variant is more flexible. If the key parameter is an empty string, a new unique key is automatically generated. However, with an explicit key, data can be replaced if the key is already in use. If an explicitly specified key does not exist, a new tuple is silently created. Keys are also byte arrays and could potentially be binary data, but commonly some readable string encoding is used. Optionally, the time-to-live of the data on the daemon can be specified. The default lifetime is 8 hours.

Tuples which are in the store longer than their lifetime are automatically retired by the daemon. Attempts to access them via their key after this point in time results in an error. The final optional argument is an integer, which can be stored as an additional tuple component.

The command returns the key of the tuple, which may have been assigned automatically.

Example:

set key [memcache put $nh $data1]
memcache put $nh $key $data2

memcache remove

memcache remove mchandle key ?ttl_secs?

Delete a tuple on the remote daemon. If the key is not valid, an error results. By default the deletion becomes effective immediate. Alternatively a time-to-live value can be specified, which schedules tuple deletion for a time in the future.

This command does not delete the interface object. For this purpose, use the memcache destroy command.

Example:

catch {memcache remove $mch $key}

This statement removes the tuple, and ignores any errors in case the key is not stored or has already timed out

memcache start

memcached start mchandle

Attempt to start all required memcached daemons associated with an interface object. If all connections are already being served, this command does nothing.

Otherwise, the command will try to start memcached executable(s) with properly configured options for a rendezvous on the named socket or socket port as specified during the interface object creation. This autostart mechanism obviously only works of the daemon is running on the same host as the application, the memcached executable is found in the search path, and the effective user of the application has sufficient permissions. Other start mechanisms must be used to assure that the required daemons are listening when using remote ports.

If there were unserved connections, and they could be activated by starting the daemon locally, the command result is 1. If any required start attempt failed, the result is 0. If the command did not need to perform any action, the result is -1.

Any newly started daemon has an empty tuple storage and no memory of any data stored by daemons previously serving the same connection.

memcache status

memcache status mchandle

Get the status of all daemons connected to the handle. If there is only a single daemon associated with the interface object, the result is a status dictionary with parameter/value pairs, otherwise a list of such dictionaries in the order of the daemons were named when the interface object was constructed. The exact contents of a status dictionary is dependent on the version of the memcached serving the connection.

In case any of the daemons associated with the interface object cannot be contacted, an error results.

Example:

echo [dict get [memcache status $mchandle] uptime]

memcache stop

memcache stop mchandle

Attempt to stop all memcached daemons associated with an interface object by sending them termination signals. This works only with local daemons and requires that the effective user of the application has sufficient rights. It has no effect on any remote daemon process.

As a side effect, all active connections to servers are closed, but they are re-activated automatically if the daemons are available once more at a time when later commands are executed with the interface object. The command does not destroy or invalidate the interface object proper. Daemons can, for example, be restarted manually or by means of the memcache start command. However, restarted daemons have no memory of tuples stored previously, so a total data loss is always a consequence when a daemon was successfully terminated by means of this command, or died because of any other reason.

The return value of the command is 1 if all daemon processes could be terminated, 0 if there were any problems such as insufficient permissions or remote daemons, and -1 if no action was required.

memcache valid

memcache valid mchandle key

A boolean check whether a given key is valid, i.e. whether data was stored with this key and has not expired. If the key is not valid, zero is returned, not an error.

Example:

if {![memcache valid $mch $mykey]} { ....