<?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:root@localhost" />
</head>
<body>
<ul id="index">
<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>
<center><h1>USER MANUAL</h1></center>
<h1 id="NAME">NAME</h1>
<p>TakTuk::Pilot - Perl module that ease <code>taktuk(1)</code> execution and related I/O management</p>
<h1 id="SYNOPSIS">SYNOPSIS</h1>
<pre><code> 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));</code></pre>
<h1 id="DESCRIPTION">DESCRIPTION</h1>
<p>The TakTuk::Pilot Perl module ease the use of <b>TakTuk</b> from within a Perl program (see <code>taktuk(1)</code> for a detailed description of <b>TakTuk</b>). It transparently manages I/O exchanges as well as <b>TakTuk</b> data demultiplexing and decoding.</p>
<h1 id="CONSTRUCTOR">CONSTRUCTOR</h1>
<dl>
<dt id="new"><b>new</b><b>()</b></dt>
<dd>
<p>Creates a new <b>TakTuk</b> object on which the following method can be called.</p>
</dd>
</dl>
<h1 id="METHODS">METHODS</h1>
<dl>
<dt id="add_callback"><b>add_callback(%)</b></dt>
<dd>
<p>Adds a callback function associated to some <b>TakTuk</b> output stream to the calling <b>TakTuk</b> object. This callback function will be called by <b>TakTuk::Pilot</b> 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>
<pre><code> 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</code></pre>
<p>The callback function should accept a hash as argument. This hash will be populated with the following fields :</p>
<pre><code> 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</code></pre>
</dd>
<dt id="send_command"><b>send_command($)</b></dt>
<dd>
<p>Sends to the calling <b>TakTuk</b> object the command passed as argument. Note that if the <b>TakTuk</b> object is not running, this command will be buffered and executed upon run.</p>
</dd>
<dt id="send_termination"><b>send_termination</b><b>()</b></dt>
<dd>
<p>Sends to the calling <b>TakTuk</b> object a termination command. As for <code>send_command</code>, if the <b>TakTuk</b> object is not running, this command will be issued upon run.</p>
</dd>
<dt id="run"><b>run(%)</b></dt>
<dd>
<p>Runs <b>TakTuk</b>, executing pending commands and waiting for <b>TakTuk</b> output. Note that this function is blocking: it waits for <b>TakTuk</b> outputs, possibly calls related callback functions and returns when <b>TakTuk</b> terminates. Thus, all <b>TakTuk</b> commands should be given either before calling <code>run</code> or within a callback function.</p>
<p>This commands takes a hash as argument that may contain the following fields:</p>
<pre><code> command => TakTuk command line to be executed
timeout => optional timeout on the wait for TakTuk output</code></pre>
<p>Upon occurence of the timeout (if one has been given), <code>run</code> will returns an <code>ETMOUT</code> error code. Note the in this case <b>TakTuk</b> execution will not be terminated and should be resumed at some point by calling <code>continue</code>.</p>
</dd>
<dt id="continue"><b>continue</b><b>()</b></dt>
<dd>
<p>Resumes a <b>TakTuk</b> execution interrupted by timeout occurence.</p>
</dd>
<dt id="add_descriptor"><b>add_descriptor(%)</b></dt>
<dd>
<p>Because the call to <code>run</code> is blocking, waiting for <b>TakTuk</b> 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 <code>add_descriptor</code>. This function takes a hash as parameter in which the following fields might be defined:</p>
<pre><code> 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</code></pre>
<p>The callback function should also accept a hash as an argument in which the following fields will be defined:</p>
<pre><code> 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</code></pre>
</dd>
<dt id="remove_descriptor"><b>remove_descriptor(%)</b></dt>
<dd>
<p>Function that should be called to remove from the <b>TakTuk</b> object a descriptor previously added with <code>add_descriptor</code>. It takes a hash as argument in which the following fields may be defined:</p>
<pre><code> type => type of I/O (see add_descriptor)
filehandle => file descriptor to remove</code></pre>
</dd>
<dt id="quiet-verbose"><b>quiet</b><b>() / verbose</b><b>()</b></dt>
<dd>
<p>Change verbosity of <code>TakTuk::Pilot</code> on STDOUT (default is quiet). Should not be called when <b>TakTuk</b> is running.</p>
</dd>
<dt id="create_session"><b>create_session</b><b>()</b></dt>
<dd>
<p>Call <code>setsid</code> in the <b>TakTuk</b> process created by <code>run</code>. The main purpose of this call is to prevent <b>TakTuk</b> from receiving signals sent to the process group to which the pilot belong. Should not be called when <b>TakTuk</b> is running.</p>
</dd>
<dt id="pid"><b>pid</b><b>()</b></dt>
<dd>
<p>Returns the pid of the process spawned to run <b>TakTuk</b>. Should only be called when <b>TakTuk</b> is running.</p>
</dd>
<dt id="error_msg"><b>error_msg($)</b></dt>
<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 (<code>add_callback</code>, <code>send_command</code>, <code>send_termination</code>, ...).</p>
</dd>
</dl>
<h1 id="ERRORS">ERRORS</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 id="TakTuk::Pilot::EARGCM"><b>TakTuk::Pilot::EARGCM</b></dt>
<dd>
<p>Field 'command' is missing in a call to <code>run</code>.</p>
</dd>
<dt id="TakTuk::Pilot::EARGCB"><b>TakTuk::Pilot::EARGCB</b></dt>
<dd>
<p>Field 'callback' is missing in a call to <code>add_callback</code> or <code>add_descriptor</code>.</p>
</dd>
<dt id="TakTuk::Pilot::EARGFH"><b>TakTuk::Pilot::EARGFH</b></dt>
<dd>
<p>Field 'filehandle' is missing in a call to <code>add_descriptor</code> or <code>remove_descriptor</code>.</p>
</dd>
<dt id="TakTuk::Pilot::EARGTP"><b>TakTuk::Pilot::EARGTP</b></dt>
<dd>
<p>Field 'type' is missing in a call to <code>add_descriptor</code> or <code>remove_descriptor</code>.</p>
</dd>
<dt id="TakTuk::Pilot::ETMOUT"><b>TakTuk::Pilot::ETMOUT</b></dt>
<dd>
<p>A timeout occured in a call to <code>run</code>.</p>
</dd>
<dt id="TakTuk::Pilot::ETKTRN"><b>TakTuk::Pilot::ETKTRN</b></dt>
<dd>
<p><b>TakTuk</b> is alredy running but <code>run</code>, <code>verbose</code> or <code>quiet</code> has been called.</p>
</dd>
<dt id="TakTuk::Pilot::ETKTNR"><b>TakTuk::Pilot::ETKTNR</b></dt>
<dd>
<p><b>TakTuk</b> is not running but <code>continue</code> has been called.</p>
</dd>
<dt id="TakTuk::Pilot::ESPIPE"><b>TakTuk::Pilot::ESPIPE</b></dt>
<dd>
<p>A call to <code>pipe</code> failed in <code>TakTuk::Pilot</code> (the error should be in $!).</p>
</dd>
<dt id="TakTuk::Pilot::ESFORK"><b>TakTuk::Pilot::ESFORK</b></dt>
<dd>
<p>A call to <code>fork</code> failed in <code>TakTuk::Pilot</code> (the error should be in $!).</p>
</dd>
<dt id="TakTuk::Pilot::ESCLOS"><b>TakTuk::Pilot::ESCLOS</b></dt>
<dd>
<p>A call to <code>close</code> failed in <code>TakTuk::Pilot</code> (the error should be in $!).</p>
</dd>
<dt id="TakTuk::Pilot::ESELEC"><b>TakTuk::Pilot::ESELEC</b></dt>
<dd>
<p>A call to <code>select</code> failed in <code>TakTuk::Pilot</code> (the error should be in $!).</p>
</dd>
<dt id="TakTuk::Pilot::ETPBUG"><b>TakTuk::Pilot::ETPBUG</b></dt>
<dd>
<p>Internal bug detected in <code>TakTuk::Pilot</code>.</p>
</dd>
</dl>
<h1 id="SEE-ALSO">SEE ALSO</h1>
<p><code>tatkuk(1)</code>, <code>taktukcomm(3)</code>, <code>TakTuk(3)</code></p>
<h1 id="AUTHOR">AUTHOR</h1>
<p>The original concept of <b>TakTuk</b> 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>
<h1 id="COPYRIGHT">COPYRIGHT</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>
distrib
>
Mageia
>
5
>
i586
>
media
>
core-release
>
by-pkgid
>
04703c89a38a0988cb5f2736c0f9a688
>
files
>
15
