The netcache Command Extension

The netcache command extension provides an interface to the NCBI netcache memory data caching daemon. This is a useful functionality especially for the implementation of stateful CGI and FCGI applications.

Since the NCBI Toolkit, which provides the basic interface functions, is difficult to compile on many platforms, this command extension is only provided as part of the standard toolkit distributions for a few select platforms. Even these packages do not contain the netcache daemon proper, only the interface module. Setting up a netcache environment is probably not justified for most application scenarios, especially since the simpler and much more portable memcache command extension and associated daemon with near equivalent functionality are now a standard toolkit component.

There is currently no Python interface to this extension.

This command extension is thread-safe.

These are the subcommands:

netcache create

netcache create clientname ?host? ?port? ?lbname?

Create a netcache daemon interface object. The command returns a handle for this object which is used by all other netcache commands to identify the interface. Multiple interfaces can be in use simultaneously.

The clientname argument is an arbitrary string which is used to identify an application, or application component. The optional host and port arguments specify the server the storage daemon is running on. If not set, they default to localhost and the default netcache port 9001. The final argument can be used to select a load balancer component. Please refer to the NCBI netcache documentation for details. The default is an empty string, i.e. the host/port combination directly selects the physical server.

Example:

set nhandle [netcache create “killerapp” $cachehost]

netcache delete

netcache delete all
netcache delete ?nhandle?...

The first command version deletes all active netcache 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 netcache 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 the 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, use the same client name, and supply the proper keys. To delete tuples, use the netcache remove command.

Example:

netcache delete $nh

netcache get

netcache get nhandle key ?listindex?

Retrieve the data associated with the specified key. The data 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. The returned data can be binary.

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 [netcache get $nh $key]

netcache list

netcache list ?pattern?

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

Example:

netcache list

netcache put

netcache put nhandle data
netcache put nhandle key data ?ttl_secs?

Store data on a netcache 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 be binary, but commonly some readable string encoding is used. Optionally, the time-to-live of the data on the daemon can be specified. The default value is part of the netcache daemon configuration and cannot be queried directly. Tuples which are in the store longer than their allowed time are automatically retired by the daemon. Attempts to access them via their key after this point in time results in an error.

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

Example:

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

netcache remove

netcache remove nhandle key

Delete a tuple on the remote daemon. If the key is not valid, an error results.

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

Example:

catch {netcache remove $nh $key}

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

netcache valid

netcache valid nhandle key

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

Example:

if {![netcache valid $nh $mykey]} { ....