NAME

RtcacheEngine - Object class to manage rtcache streams

SYNOPSIS

import rtcache

rtce = rtcache.RtcacheEngine( streamname, pfdict )

rtce.startup()
rtce.update()
rtce.harvest()
rtce.shutdown()

rtce.inform( message)

DESCRIPTION

Overview

For each stream of objects which the rtcache(1) program is responsible for caching and delivering, a Python object manages all startup tasks, updating tasks, harvesting tasks, and shutdown tasks for that stream. The RtcacheEngine class is the base for instantiating these streams. By design the end user will neither instantiate these objects nor call their methods directly. Rather, the user will enter configuration parameters for these objects in the rtcache.pf parameter-file, after which the rtcache program will instantiate all necessary RtcacheEngine objects and call their methods when necessary.

Methods

The constructor for the RtcacheEngine objects takes two arguments, the string name for the stream as streamname and the Python hash equivalent of an Antelope parameter-file used to configure the stream, given as the pfdict parameter. The RtcacheEngine object has four main methods, called startup, update, harvest, and shutdown, which are invoked by the rtcache program to accomplish these tasks. The harvest method is handed the request parameter-file as its first (and only) input argument, in the form of a python dictionary. There is also an inform method for the RtcacheEngine object which is invoked under rtcache(1) verbose mode to emit informational messages.

Engine Types

The RtcacheEngine object may be configured as one of several different engine types.

• xwindow
  The xwindow engine type allows the user to run a process that produces one X-window Graphical User Interface (GUI) display. Graphical output for the process is directed to a virtual X-server launched by the object. Upon harvest requests for the stream, screen-dumps are taken of the X-window for the process, converted to an appropriate image type, and placed upon the output orb server.
• diy
  The diy engine type, short for Do-It-Yourself, yields full control over object behavior to the end user, who may encode their own startup, update, harvest, and shutdown scripts into the parameter file. All process launches, intermediate steps to generate stream contents, orb output interactions, and shutdown tasks are the responsibility of the end user writing the parameter file. Within the harvest script, the request parameter file is available as the python dictionary variable called pfdict_request.

PARAMETER FILE

The parameter-file entries for a given RtcacheEngine object are actually contained as a sub-parameter-file within rtcache.pf for the rtcache(1) program.

common

All engine types contain the following parameters:

• enginetype
  This required parameter specifies the engine type, and determines how further parameters are interpreted. Currently the supported enginetypes are diy and xwindow.
• diagnostics
  This boolean parameter turns on debugging messages. It is intended for developers, not for normal use. Turning on diagnostics automatically turns on verbose. If not present, it defaults to 0.

enginetype xwindow

The xwindow engine type requires the following configuration parameters:

• command
  The command parameter specifies a Unix command-line command to run that generates the GUI whose screen-dump images will be harvested. This may be either a string with the executable and all arguments concatenated together, or a parameter-file &Tbl with each argument on a separate line.
• command_env
  The command_env array contains key/value pairs of environment variables to set, under which the given command will run. Commonly this will at least include the ANTELOPE environment variable. It is neither necessary nor advisable to set the DISPLAY environment variable explicitly in this array, since the display parameters are managed internally by RtcacheEngine.
• image_format
  Images harvested by the xwindow engine are converted by the Python Imaging Library to the format specified by image_format.
• startup_sleep_sec
  This parameter specifies a number of seconds to sleep after launching initial processes before proceeding.
• xwindow_restart_sec
  If this parameter is present and nonzero, the X virtual frame buffer and the X-windows command running in it will be restarted periodically. This is useful to reign in imperfectly behaving display scripts and/or X virtual display programs. The restarting process automatically resets virtual_display to auto.
• virtual_display
  The virtual_display parameter gives the name of the X-window display which the virtual X-server will serve. If this parameter is set to auto, the xwindow engine attempts to choose an appropriate display number automatically.
• virtual_screen_number
  The virtual_screen_number parameter gives the screen number to use for the X-window display. This parameter is optional and if not present or if empty, it defaults to 0.
• virtual_screen_geometry
  The virtual_screen_geometry parameter gives the width and height to use to configure the virtual screen. The value is specified as the number of pixels for the width, an x character, then the number of pixels for the height, with no spaces, e.g. 1280x1024. If this parameter is left blank, a default value of 1280x1024 is assumed.
• window_name
  If the window_name parameter is not blank, the xwindow engine assumes the given value is the exact name of the X-window for the GUI application being run. The xwindow engine then uses this name in its attempt to dump the window for the GUI application. If window_name is blank, the xwindow engine attempts to harvest the correct window automatically by searching for a window of any name that is of believable size for an X application worth monitoring (currently at least 10x10 pixels).

enginetype diy

The diy engine type requires the following configuration parameters:

• startup_script
  The startup_script parameter must be a parameter-file &Literal value containing a Python script to be run in order to initiate the stream.
• update_script
  The update_script parameter must be a parameter-file &Literal value containing a Python script to be run in order to update the stream, usually pre-computing any behind-the-scenes information products and/or assuring the health of running sub-processes.
• harvest_script
  The harvest_script parameter must be a parameter-file &Literal value containing a Python script to be run in order to harvest one copy of the stream object and put it on the output orbserver.
• shutdown_script
  The shutdown_script parameter must be a parameter-file &Literal value containing a Python script to be run in order to close the stream and clean up all resources used.

RETURN VALUES

The RtcacheEngine constructor returns an object instantiated from the RtcacheEngine class.

SEE ALSO

rtcache(1)

BUGS AND CAVEATS

Because the content of the diy engine's startup_script, harvest_script, update_script, and shutdown_script parameters are given to a Python interpreter, they must be indented properly (no tab characters, and with indentation level having syntactic meaning). However, any uniform level of indentation will be removed from each of these parameters before the contents are given to the Python interpreter, allowing the rtcache.pf parameter-file to be lined up in an easily readable layout. The color depth for the xwindow engine is hard-wired to 24 bits to support the current screen-grabbing and image-conversion strategy. Images less than 10 pixels wide or high will be ignored by the xwindow engine due to the way the search is handled for the correct window inside the virtual server display. This strategy could perhaps be improved. display ports for xwindow style engines are allocated first-come, first-serve (usually in alphabetical order based on streamname). This means that if an engine with virtual_display set to auto grabs a particular display port, any engine that comes along afterwards with a manual setting requesting that display port will fail because the port is already taken. The automatic search for a display number will stop after failing with a contiguous block of successive candidate ports. Currently this search limit is hard-wired to 100 ports. The update_script is intended to be fairly lightweight, finishing quickly with the possible exception of the initial run at startup. If this is not true, incoming requests may time-out if any one update procedure takes too long. rtcache has no way of stopping a long-running update_script.

AUTHOR

Kent Lindquist