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.
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
daemon proper, only the interface module. Setting up a
environment is probably not justified for most application scenarios, especially since the simpler and much more portable
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:
daemon interface object. The command returns a handle for this object which is used by all other
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.
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.
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
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.
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.