• Antelope Release 5.3 SunOS 5.10 2013-12-18

 

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

PARAMETER FILE

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
Printer icon