Apache::Wyrd::Bot - Spawn a process and monitor it
<BASENAME::Bot basefile="/var/www/watchme" perl="/usr/bin/perl" />
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.
/path/to/perl -MBOTCLASSNAME -ego
_work
(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.
Absolute pathnames for the files normally derived from basefile can be specified, if necessary.
How many seconds between browser refreshes. Default is 2.
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.
Absolute path to the perl executeable. Bot will attempt to determine this itself, but it is best if it is explicitly declared.
Use when output is not HTML. Causes the Wyrd to use <PRE></PRE> to enclose the output of the 'Bot.
Display the lines of the output file in reverse.
(format: (returns) name (arguments after self))
params
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.
$self->
The other use is for creating a base class of 'Bots from which bots that perform different jobs can be derived.
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.)
print()
carp()
warn()
die()
exit()
The default _work is to count to 20.
_process_results
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.
_format_output
errfile
expire
go
lib
outfile
perl
pidfile
refresh
template
_cleanup
_go
_init_params
_message
_prepare
_process_params
_read_message
_write_message
Barry King <wyrd@nospam.wyrdwright.com>
General-purpose HTML-embeddable perl object
Copyright 2002-2007 Wyrdwright, Inc. and licensed under the GNU GPL.
See LICENSE under the documentation for Apache::Wyrd.
Apache::Wyrd
To install Apache::Wyrd, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Apache::Wyrd
CPAN shell
perl -MCPAN -e shell install Apache::Wyrd
For more information on module installation, please visit the detailed CPAN module installation guide.