<?xml version="1.0" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>TakTuk</title>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:_www@b70.apple.com" />
</head>
<body style="background-color: white">
<p><a name="__index__"></a></p>
<!-- INDEX BEGIN -->
<ul>
<li><a href="#name">NAME</a></li>
<li><a href="#synopsis">SYNOPSIS</a></li>
<li><a href="#description">DESCRIPTION</a></li>
<li><a href="#constructor">CONSTRUCTOR</a></li>
<li><a href="#methods">METHODS</a></li>
<li><a href="#errors">ERRORS</a></li>
<li><a href="#see_also">SEE ALSO</a></li>
<li><a href="#author">AUTHOR</a></li>
<li><a href="#copyright">COPYRIGHT</a></li>
</ul>
<!-- INDEX END -->
<hr />
<center><h1>USER MANUAL</h1></center><p>
</p>
<hr />
<h1><a name="name">NAME</a></h1>
<p>TakTuk::Pilot - Perl module that ease <code>taktuk(1)</code> execution and related I/O
management</p>
<p>
</p>
<hr />
<h1><a name="synopsis">SYNOPSIS</a></h1>
<pre>
use TakTuk::Pilot;
our @line_counter;
sub output_callback(%) {
my %parameters = @_;
my $field = $parameters{fields};
my $rank = $field->{rank};
my $argument = $parameters{argument};
$argument->[$rank] = 1 unless defined($argument->[$rank]);
print "$field->{host}-$rank : ".
"$argument->[$rank] > $field->{line}\n";
$argument->[$rank]++;
}
sub user_input_callback(%) {
my %parameters = @_;
my $taktuk = $parameters{taktuk};
my $descriptor = $parameters{filehandle};
my $buffer;
my $result = sysread($descriptor, $buffer, 1024);
warn "Read error $!" if not defined($result);
# basic parsing, we assume input is buffered on a line basis
chomp($buffer);
if (length($buffer)) {
print "Executing $buffer\n";
$taktuk->send_command("broadcast exec [ $buffer ]");
}
if (not $result) {
print "Terminating\n";
$taktuk->remove_descriptor(type=>'read',
filehandle=>$descriptor);
$taktuk->send_termination();
}
}
die "This script requieres as arguments hostnames to contact\n"
unless scalar(@ARGV);
my $taktuk = TakTuk::Pilot->new();
$taktuk->add_callback(callback=>\&output_callback, stream=>'output',
argument=>\@line_counter,
fields=>['host', 'rank', 'line']);
$taktuk->add_descriptor(type=>'read', filehandle=>\*STDIN,
callback=>\&user_input_callback);
$taktuk->run(command=>"taktuk -s -m ".join(" -m ", @ARGV));</pre>
<p>
</p>
<hr />
<h1><a name="description">DESCRIPTION</a></h1>
<p>The TakTuk::Pilot Perl module ease the use of <strong>TakTuk</strong> from within a Perl
program (see <code>taktuk(1)</code> for a detailed description of <strong>TakTuk</strong>). It
transparently manages I/O exchanges as well as <strong>TakTuk</strong> data demultiplexing
and decoding.</p>
<p>
</p>
<hr />
<h1><a name="constructor">CONSTRUCTOR</a></h1>
<dl>
<dt><strong><a name="item_new"><strong>new</strong><strong>()</strong></a></strong>
<dd>
<p>Creates a new <strong>TakTuk</strong> object on which the following method can be called.</p>
</dd>
</li>
</dl>
<p>
</p>
<hr />
<h1><a name="methods">METHODS</a></h1>
<dl>
<dt><strong><a name="item_add_callback"><strong>add_callback(%)</strong></a></strong>
<dd>
<p>Adds a callback function associated to some <strong>TakTuk</strong> output stream to the
calling <strong>TakTuk</strong> object. This callback function will be called by
<strong>TakTuk::Pilot</strong> for each batch of output data incoming from the related
stream. The hash passed as argument to this function call may contain the
following fields:</p>
</dd>
<dd>
<pre>
callback => reference to the callback fonction (mandatory)
stream => stream related to this callback, might be
'default' (mandatory)
fields => reference to an array of fields names relevant
to the user
argument => scalar that should be passed to each callback
function call</pre>
</dd>
<dd>
<p>The callback function should accept a hash as argument. This hash will be
populated with the following fields :</p>
</dd>
<dd>
<pre>
taktuk => reference to the taktuk object calling this
callback
argument => scalar given at callback addition or undef
stream => stream on which output data came
fields => reference to a hash containing a
fieldname/value pair for each field requested
upon callback addition</pre>
</dd>
</li>
<dt><strong><a name="item_send_command"><strong>send_command($)</strong></a></strong>
<dd>
<p>Sends to the calling <strong>TakTuk</strong> object the command passed as argument. Note that
if the <strong>TakTuk</strong> object is not running, this command will be buffered and
executed upon run.</p>
</dd>
</li>
<dt><strong><a name="item_send_termination"><strong>send_termination</strong><strong>()</strong></a></strong>
<dd>
<p>Sends to the calling <strong>TakTuk</strong> object a termination command. As for
<a href="#item_send_command"><code>send_command</code></a>, if the <strong>TakTuk</strong> object is not running, this command will be
issued upon run.</p>
</dd>
</li>
<dt><strong><a name="item_run"><strong>run(%)</strong></a></strong>
<dd>
<p>Runs <strong>TakTuk</strong>, executing pending commands and waiting for <strong>TakTuk</strong> output.
Note that this function is blocking: it waits for <strong>TakTuk</strong> outputs, possibly
calls related callback functions and returns when <strong>TakTuk</strong> terminates. Thus,
all <strong>TakTuk</strong> commands should be given either before calling <a href="#item_run"><code>run</code></a> or within a
callback function.</p>
</dd>
<dd>
<p>This commands takes a hash as argument that may contain the following fields:</p>
</dd>
<dd>
<pre>
command => TakTuk command line to be executed
timeout => optional timeout on the wait for TakTuk output</pre>
</dd>
<dd>
<p>Upon occurence of the timeout (if one has been given), <a href="#item_run"><code>run</code></a> will returns an
<code>ETMOUT</code> error code. Note the in this case <strong>TakTuk</strong> execution will not be
terminated and should be resumed at some point by calling <a href="#item_continue"><code>continue</code></a>.</p>
</dd>
</li>
<dt><strong><a name="item_continue"><strong>continue</strong><strong>()</strong></a></strong>
<dd>
<p>Resumes a <strong>TakTuk</strong> execution interrupted by timeout occurence.</p>
</dd>
</li>
<dt><strong><a name="item_add_descriptor"><strong>add_descriptor(%)</strong></a></strong>
<dd>
<p>Because the call to <a href="#item_run"><code>run</code></a> is blocking, waiting for <strong>TakTuk</strong> output, it might
be interesting to let the <code>TakTuk::Pilot</code> module monitor I/O occurence related
to other file descriptors.
This is the intent of <a href="#item_add_descriptor"><code>add_descriptor</code></a>. This function takes a hash as
parameter in which the following fields might be defined:</p>
</dd>
<dd>
<pre>
type => 'read', 'write' or 'exception', this is the
type of I/O possiblities that should be
monitored on the descriptor, as in select
system call (mandatory).
filehandle => file descriptor to monitor (mandatory).
callback => reference to the callback function that
should be called when I/O is possible on the
file descriptor.
argument => optional scalar value that will be passed
with each call to the callback function</pre>
</dd>
<dd>
<p>The callback function should also accept a hash as an argument in which the
following fields will be defined:</p>
</dd>
<dd>
<pre>
taktuk => reference to the TakTuk object from which
the function was called.
type => type of I/O occuring (as in add_callback)
filehandle => the related file descriptor. Notice that the
user is in charge of performing the I/O
operation itslef (sysread or syswrite).
Notice also that, because of the use of a
select in TakTuk::Pilot, the use of buffered
I/O on this descriptor is strongly discouraged
argument => the argument that was given to add_descriptor</pre>
</dd>
</li>
<dt><strong><a name="item_remove_descriptor"><strong>remove_descriptor(%)</strong></a></strong>
<dd>
<p>Function that should be called to remove from the <strong>TakTuk</strong> object a descriptor
previously added with <a href="#item_add_descriptor"><code>add_descriptor</code></a>. It takes a hash as argument in which
the following fields may be defined:</p>
</dd>
<dd>
<pre>
type => type of I/O (see add_descriptor)
filehandle => file descriptor to remove</pre>
</dd>
</li>
<dt><strong><a name="item_quiet"><strong>quiet</strong><strong>() / verbose</strong><strong>()</strong></a></strong>
<dd>
<p>Change verbosity of <code>TakTuk::Pilot</code> on STDOUT (default is quiet). Should not
be called when <strong>TakTuk</strong> is running.</p>
</dd>
</li>
<dt><strong><a name="item_error_msg"><strong>error_msg($)</strong></a></strong>
<dd>
<p>Static function. Returns a character string that corresponds to the error code
given as argument. The error code should be one of the values returned by other
<code>TakTuk::Pilot</code> functions (<a href="#item_add_callback"><code>add_callback</code></a>, <a href="#item_send_command"><code>send_command</code></a>,
<a href="#item_send_termination"><code>send_termination</code></a>, ...).</p>
</dd>
</li>
</dl>
<p>
</p>
<hr />
<h1><a name="errors">ERRORS</a></h1>
<p>When an error occur in one of these functions, it returns a non nul numeric
error code. This code can take one of the following values:</p>
<dl>
<dt><strong><a name="item_taktuk_3a_3apilot_3a_3aeargcm"><strong>TakTuk::Pilot::EARGCM</strong></a></strong>
<dd>
<p>Field 'command' is missing in a call to <a href="#item_run"><code>run</code></a>.</p>
</dd>
</li>
<dt><strong><a name="item_taktuk_3a_3apilot_3a_3aeargcb"><strong>TakTuk::Pilot::EARGCB</strong></a></strong>
<dd>
<p>Field 'callback' is missing in a call to <a href="#item_add_callback"><code>add_callback</code></a> or <a href="#item_add_descriptor"><code>add_descriptor</code></a>.</p>
</dd>
</li>
<dt><strong><a name="item_taktuk_3a_3apilot_3a_3aeargfh"><strong>TakTuk::Pilot::EARGFH</strong></a></strong>
<dd>
<p>Field 'filehandle' is missing in a call to <a href="#item_add_descriptor"><code>add_descriptor</code></a> or
<a href="#item_remove_descriptor"><code>remove_descriptor</code></a>.</p>
</dd>
</li>
<dt><strong><a name="item_taktuk_3a_3apilot_3a_3aeargtp"><strong>TakTuk::Pilot::EARGTP</strong></a></strong>
<dd>
<p>Field 'type' is missing in a call to <a href="#item_add_descriptor"><code>add_descriptor</code></a> or
<a href="#item_remove_descriptor"><code>remove_descriptor</code></a>.</p>
</dd>
</li>
<dt><strong><a name="item_taktuk_3a_3apilot_3a_3aetmout"><strong>TakTuk::Pilot::ETMOUT</strong></a></strong>
<dd>
<p>A timeout occured in a call to <a href="#item_run"><code>run</code></a>.</p>
</dd>
</li>
<dt><strong><a name="item_taktuk_3a_3apilot_3a_3aetktrn"><strong>TakTuk::Pilot::ETKTRN</strong></a></strong>
<dd>
<p><strong>TakTuk</strong> is alredy running but <a href="#item_run"><code>run</code></a>, <code>verbose</code> or <a href="#item_quiet"><code>quiet</code></a> has been called.</p>
</dd>
</li>
<dt><strong><a name="item_taktuk_3a_3apilot_3a_3aetktnr"><strong>TakTuk::Pilot::ETKTNR</strong></a></strong>
<dd>
<p><strong>TakTuk</strong> is not running but <a href="#item_continue"><code>continue</code></a> has been called.</p>
</dd>
</li>
<dt><strong><a name="item_taktuk_3a_3apilot_3a_3aespipe"><strong>TakTuk::Pilot::ESPIPE</strong></a></strong>
<dd>
<p>A call to <code>pipe</code> failed in <code>TakTuk::Pilot</code> (the error should be in $!).</p>
</dd>
</li>
<dt><strong><a name="item_taktuk_3a_3apilot_3a_3aesfork"><strong>TakTuk::Pilot::ESFORK</strong></a></strong>
<dd>
<p>A call to <code>fork</code> failed in <code>TakTuk::Pilot</code> (the error should be in $!).</p>
</dd>
</li>
<dt><strong><a name="item_taktuk_3a_3apilot_3a_3aesclos"><strong>TakTuk::Pilot::ESCLOS</strong></a></strong>
<dd>
<p>A call to <code>close</code> failed in <code>TakTuk::Pilot</code> (the error should be in $!).</p>
</dd>
</li>
<dt><strong><a name="item_taktuk_3a_3apilot_3a_3aeselec"><strong>TakTuk::Pilot::ESELEC</strong></a></strong>
<dd>
<p>A call to <code>select</code> failed in <code>TakTuk::Pilot</code> (the error should be in $!).</p>
</dd>
</li>
<dt><strong><a name="item_taktuk_3a_3apilot_3a_3aetpbug"><strong>TakTuk::Pilot::ETPBUG</strong></a></strong>
<dd>
<p>Internal bug detected in <code>TakTuk::Pilot</code>.</p>
</dd>
</li>
</dl>
<p>
</p>
<hr />
<h1><a name="see_also">SEE ALSO</a></h1>
<p><code>tatkuk(1)</code>, <code>taktukcomm(3)</code>, <code>TakTuk(3)</code></p>
<p>
</p>
<hr />
<h1><a name="author">AUTHOR</a></h1>
<p>The original concept of <strong>TakTuk</strong> has been proposed by Cyrille Martin in his
PhD thesis. People involved in this work include Jacques Briat, Olivier
Richard, Thierry Gautier and Guillaume Huard.</p>
<p>The author of the version 3 (perl version) and current maintainer of the
package is Guillaume Huard.</p>
<p>
</p>
<hr />
<h1><a name="copyright">COPYRIGHT</a></h1>
<p>The <code>TakTuk</code> communication interface library is provided under the terms
of the GNU General Public License version 2 or later.</p>
</body>
</html>
