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.
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.
set nhandle [netcache create “killerapp” $cachehost]
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.
netcache delete $nh
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.
set data [netcache get $nh $key]
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.
netcache list
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.
set key [netcache put $nh $data1]
netcache put $nh $key $data2
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.
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.