NAME
rtcache - generate and cache information products and service requests for them
SYNOPSIS
rtcache [-v] [-V] [-p pfname] [-S statefile] [-t targetname] orb [pfplainref value [pfplainref value]...]
DESCRIPTION
Overview
The
rtcache program reads an Antelope parameter-file which describes how to generate cached information products.
Multiple
streams of cached objects may be defined. Each
stream has its own startup parameters, update steps, harvest
parameters, and shutdown steps, as well as its own unique name. Clients of
rtcache may post requests for the
latest product in a given
stream, then receive a copy of that product after
rtcache retrieves it from internal
storage or harvests the latest copy. All communication between
rtcache and its clients is brokered by an orbserver:
requests for a copy of the latest product in a
stream are posted to an orbserver as parameter file packets, and
replies from
rtcache containing the requested product are posted as orbserver packets in the format appropriate to the
result.
Requests for the latest snapshot of an information product may be posted to the named
orb orbserver
as packets of type
[target]/pf/rtcacherequest, with the optional
target specifying the
targetname
with which
rtcache was launched. If no target is specified via the
-t option,
rtcache listens
for and attempts to respond to all packets of type
.*/pf/rtcacherequest.
The
rtcache command-line may contain additional key-value pairs after the specified
orb. These key-value pairs
are inserted into the
rtcache.pf parameter-file before that parameter-file is interpreted. These keys may then be used
as parameter-file plain references (see
pf(5) for an explanation of plain references). Most commonly this may be used to specify additional
orbservers on the
rtcache command-line, to be used in the invocation of xwindow-based subcommands whose screen dumps are served as
rtcache streams.
Stream Engines
Each
stream of objects cached by
rtcache is managed by an instance of the Python
RtcacheEngine(3y) class.
An object in this class contains four main callback methods invoked by
rtcache:
startup,
update,
harvest,
and
shutdown (although for some types of engines the implementation and invocation of those callback methods
may be entirely encapsulated and hidden so the end user does not have to configure them directly). When
rtcache
starts up, it calls the
startup method for all configured
streamnames. Those
startup methods
perform any necessary set up tasks for the named
stream. After running the
startup method,
rtcache immediately runs
the
update method for each
streamname in case initial computations need to be made. After this initialization,
rtcache
reruns the
update method for each
streamname at periodic intervals, with spacing determined by the
update_interval_sec parameter in the
rtcache parameter-file.
Whenever
rtcache gets an incoming request for one
of the objects in a
stream,
rtcache calls the
harvest method
for that
stream to get a copy of the object. Under normal circumstances that resulting cached object is then put back onto the
Antelope orbserver as an orb packet. Finally, when
rtcache needs to shut down a given
stream, it calls the
shutdown
method of the
RtcacheEngine(3y) object. For further details on the specific capabilities and configuration of the
RtcacheEngine(3y), see the
RtcacheEngine(3y) man-page.
Request packets
In order to get a copy of the latest object in a particular
streamname, a remote client needs to put a request
packet on the
orb to which
rtcache is listening. This request packet needs to be of type
/pf/rtcacherequest.
Optionally, the
srcname of this
orb packet may be preceded by the
targetname of the
rtcache instance
intended to handle the request. The contents of the packet must be a parameter-file with at least one parameter
streamname,
whose value should be the name of the
stream for which to extract the latest packet (i.e. the same as the
streamname
in the
caches array of the
rtcache parameter file). The request packet may contain other parameters as well. The contents
of the request parameter file are passed to the harvest script in the form of a python dictionary as
pfdict_request.
OPTIONS
-
-p pfname
Specify a parameter-file name other than the default rtcache.pf
-
-t targetname
Specify a target name for this instance of rtcache. The default target name is rtcache.
-
-S statefile
Specify a state file for the orbserver connection
-
-v
Verbose
-
-V
Print version and usage information
PARAMETER FILE
-
request_queuesize
Incoming requests are placed on a reap-thread queue of maximum size request_queuesize, to be processed as soon as possible
by rtcache (the request_queuesize parameter is given to the orbreapthr_new function as the queuesize argument;
for mor details see the man-page orbreapthr(3)).
-
update_interval_sec
The rtcache program periodically runs the update scripts for each cache stream. The update_interval_sec
parameter specifies how often this happens, in seconds.
-
startup_failure_fatal
The boolean parameter startup_failure_fatal governs whether rtcache exits immediately if one of the
stream startup scripts fails, or merely deletes that stream and continues setting up the others.
-
caches
The caches array contains sub-arrays for the streams of objects which rtcache is responsible for being able to
generate, cache, and emit upon request. Each sub-array must have a unique name, which corresponds to the name of the
object stream under which requests for one of the objects may be made.
-
caches{streamname}
The sub-array for each streamname contains parameters specifying how that stream of objects is generated. Each
sub-array configures one instance of the RtcacheEngine(3y) object to manage the stream. If a sub-array of
caches named defaults is present, the sub-array for each streamname is initialized with those values,
which are retained unless overridden by the sub-array for the specific streamname. Several different engine types
are available, depending on the type of objects to be generated for the stream. For further information on the details of
this sub-array and the various ways to configure the engines, see the man-page for RtcacheEngine(3y).
-
caches{defaults}
The caches array may contain a sub-array called defaults, with default parameters for all or most of the
streamname sub-arrays. These values may then be left out of each streamname sub-array unless the user
needs to override one or more of them. The defaults sub-array is optional, however if it is omitted, the
sub-arrays for all of the other streamnames must of course be fully specified with no omitted parameters
(the type of engine being launched determines which parameters are expected: see the man-page RtcacheEngine(3y)
for what those parameters must be).
-
python_startup_script
The python_startup_script parameter contains a string &Literal with the startup script for the Python interpreter
to execute before launching any engine objects. Under normal conditions this parameter should not need to be modified
by the user.
EXAMPLE
% pfecho rtcache
caches &Arr{
orbrtd &Arr{
enginetype xwindow
command &Tbl{
orbrtd
-backup
100.0
dataorb
:brtt4
}
command_env &Arr{
ANTELOPE &env(ANTELOPE)
PATH &env(PATH)
PFPATH &env(PFPATH)
}
image_format GIF
virtual_display :1
virtual_screen_geometry 2560x2048
startup_sleep_sec 1
xwindow_restart_sec 0
}
}
python_startup_script &Literal{
import os
import sys
sys.path.append(os.environ['ANTELOPE'] + "/data/python")
from rtcache.rtcache import *
}
% rtcache -v :brtt5
SEE ALSO
rtwebserver(1), RtcacheEngine(3y)
BUGS AND CAVEATS
The python scripts embedded in the parameter file
&Literal values are still python scripts, and thus sensitive to
proper and consistent indentation, avoidance of tabs, etc. A uniform indent level may be added to the
python_startup_script,
which will be removed before handing the script to the Python interpreter, however this unindenting is based entirely on the
number of spaces at the beginning of the first line of the script, and supports only the ASCII space character itself (an
attempt is made to accommodate tab characters, assuming a tab stop equivalent to eight spaces, however this assumption may not be
applicable for all systems and thus tabs are discouraged).
It is not allowed to have a
stream by the name of
defaults, due to the parameter-file mechanism described above to specify
default values for the
streams.
When
rtcache starts up, it will not be ready to honor requests for up to several minutes until it has initialized all of
the cache engines and completed the initial run of their update scripts.
Key/value pairs listed on the command-line to be used as plain references in the parameter file must not have key names that overlap
with existing parameters, otherwise the latter will be overwritten. Also, the key may not have the name
outputorb since that
is hard-wired to represent (in the parameter file) the main
orb listed on the command line.
AUTHOR
Kent Lindquist