NAME

Apache::Wyrd::Bot - Spawn a process and monitor it

SYNOPSIS

<BASENAME::Bot basefile="/var/www/watchme" perl="/usr/bin/perl" />

DESCRIPTION

The Bot Wyrd provides a class of objects which operate in the background and independent of the apache process, while being monitored in a browser window. This is useful for showing updates to a time-consuming process, such as building an index or converting a file between different formats.

Because it uses HTML http-equivalent metadata to trigger the browser reload, it should always be the outermost Wyrd on an HTML page.

Bot uses the default UNIX shell and the machine filesystem to communicate with the apache process. If another instance of the 'bot is launched, this will be detected, and the browser will continue to follow the previous instance.

Unlike other Wyrds, 'Bots have two methods of being invoked. One is via the shell, using /path/to/perl -MBOTCLASSNAME -ego. This ultimately invokes the _work method. The other is via the traditional Wyrd route, and creates the reloading page.

HTML ATTRIBUTES

basefile

(Required, absolute path) The "base" file location for the 'bot to store it's process ID, output, and error log. These will be files with this base name plus .pid, .out, and .err respectively. They must be readable and writeable by the apache process. Note that they do not need to be in a browser-accessible place on the filesystem.

pidfile, errfile, outfile

Absolute pathnames for the files normally derived from basefile can be specified, if necessary.

refresh

How many seconds between browser refreshes. Default is 2.

expire

If the user does not wait for the 'bot to complete and instead closes the browser window, the previous instance will not have it's results automatically removed. This parameter defines how old the results should be before a completely new instance is invoked. The default is 30 seconds, but it shouldn't be much less than this.

perl

Absolute path to the perl executeable. Bot will attempt to determine this itself, but it is best if it is explicitly declared.

Flags

raw

Use when output is not HTML. Causes the Wyrd to use <PRE></PRE> to enclose the output of the 'Bot.

reverse

Display the lines of the output file in reverse.

PERL METHODS

(format: (returns) name (arguments after self))

(hashref) params (void)

Provide a reference to a hash of attribute value pairs to give defaults to attributes. The params method is called at runtime, so it has all Wyrd methods available to it and can be used to pass CGI data to the bot before launching it as a process. The spawned bot can access this data by calling referring to $self->{<keyname>} or calling a method with that keyname.

The other use is for creating a base class of 'Bots from which bots that perform different jobs can be derived.

(hashref) _work (void)

Perform the actual work of the 'Bot. Output (what you want to have appear on the web page) should be sent to STDOUT (i.e. use plain print()) and errors should be sent to STDERR (i.e. use plain carp(), warn(), etc.). Do not explicitly exit unless the process must be terminated irregularly (i.e. using die(), exit(), etc.)

The default _work is to count to 20.

(void) _process_results (scalar, scalar)

BUGS/CAVEATS

Spawns shells, invokes interpreters. All security caveats associated with these actions must be taken into account.

Many reserved methods in addition to _format_output: errfile, expire, go, lib, outfile, params, perl, pidfile, refresh, template, _cleanup, _go, _init_params, _message, _prepare, _process_params, _read_message, _write_message.

AUTHOR

Barry King <wyrd@nospam.wyrdwright.com>

SEE ALSO

Apache::Wyrd

General-purpose HTML-embeddable perl object

LICENSE

Copyright 2002-2007 Wyrdwright, Inc. and licensed under the GNU GPL.

See LICENSE under the documentation for Apache::Wyrd.