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