view release on metacpan or  search on metacpan

Wyrd/Bot.pm  view on Meta::CPAN

package Apache::Wyrd::Bot;
use 5.006;
use strict;
use warnings;
use base qw(Apache::Wyrd::Interfaces::Setter Apache::Wyrd);
use Apache::Wyrd::Services::SAK qw(slurp_file);
use XML::Dumper;
our $VERSION = '0.98';

=pod

=head1 NAME

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

=head1 SYNOPSIS

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

=head1 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 C</path/to/perl -MBOTCLASSNAME
-ego>. This ultimately invokes the C<_work> method. The
other is via the traditional Wyrd route, and creates the
reloading page.

=head2 HTML ATTRIBUTES

=over

=item 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.

=item pidfile, errfile, outfile

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

=item refresh

How many seconds between browser refreshes.  Default is 2.

=item 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.

=item perl

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

=item Flags

=over