<?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@b02.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="#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 - Perl module that provides an interface to <code>taktuk(1)</code> communication
facilities</p>
<p>
</p>
<hr />
<h1><a name="synopsis">SYNOPSIS</a></h1>
<pre>
use TakTuk;
my $rank = TakTuk::get('rank');
my $count = TakTuk::get('count');
print "I'm process $rank among $count\n";
if ($rank > 1) {
my ($from, $message) = TakTuk::recv();
if (not defined($message)) {
print "Trying to recv: ",
TakTuk::error_msg($TakTuk::error), "\n";
} else {
print "$rank received $message from $from\n";
}
}
sleep 1;
my $next = $rank+1;
$next = 1 if ($next > $count);
if (not TakTuk::send(to=>$next, body=>"[Salut numero $rank]")) {
print "Trying to send to $next: ",
TakTuk::error_msg($TakTuk::error), "\n";
}
if ($rank == 1) {
my ($from, $message) = TakTuk::recv(timeout=>5);
if (not defined($message)) {
print "Trying to recv :",
TakTuk::error_msg($TakTuk::error), "\n";
} else {
print "$rank received $message from $from\n";
}
}</pre>
<p>
</p>
<hr />
<h1><a name="description">DESCRIPTION</a></h1>
<p>The <strong>TakTuk</strong> communication layer Perl interface provides a way for programs
executed using the <code>taktuk(1)</code> command to exchange data. It is based on a
simple send/receive model using multicast-like sends and optionally timeouted
receives. This is only designed to be a control facility, in particular this
is not a high performance communication library.</p>
<p>The Perl communication interface for <strong>TakTuk</strong> is made of functions that can be
called by scripts executed using the <code>taktuk_perl</code> command of the <strong>TakTuk</strong>
engine (prefered way, less installation requirements on remote machines) or
using the <strong>TakTuk</strong> Perl module provided with the <strong>TakTuk</strong> distribution.
These functions are:</p>
<dl>
<dt><strong><a name="item_get"><strong>TakTuk::get($)</strong></a></strong>
<dd>
<p>gets some information from <strong>TakTuk</strong>. Currently available informations are
'rank', 'count', 'father', 'child_min' and 'child_max'. This is a better way to
get these informations than environment variables as its takes into account
renumbering that might occur after process spawn.</p>
</dd>
</li>
<dt><strong><a name="item_send"><strong>TakTuk::send(%)</strong></a></strong>
<dd>
<p>sends a scalar to a single peer or a set specification (see <code>taktuk(1)</code> for
informations about set specifications). The two mandatory fields in the
arguments are <code>to</code> (with a set specification) and <code>body</code>. Optionally, a field
<code>target</code> might be given. Returns an undefined value upon error.</p>
</dd>
</li>
<dt><strong><a name="item_recv"><strong>TakTuk::recv(%)</strong></a></strong>
<dd>
<p>blocks until the reception of a message. Returns a list of two elements:
the logical number of the source of the message and the message itself.
Accepts an optional <code>timeout</code> argument with a numeric value.
Returns an empty list upon error.</p>
</dd>
</li>
</dl>
<p>When an error occur, all these functions set the variable <code>$TakTuk::error</code>
to the numeric code of the error that occured. A textual description of the
error is provided by the function <code>TakTuk::error_msg($)</code> that takes the error
code as an argument.</p>
<p>Error codes are the following :</p>
<dl>
<dt><strong><a name="item_taktuk_3a_3aeswrit">TakTuk::ESWRIT</a></strong>
<dd>
<p>a call to <code>TakTuk::syswrite</code> failed. This is due to a <code>syswrite</code> error
different than <code>EAGAIN</code>. The code should be accessible using <code>$!</code>.</p>
</dd>
</li>
<dt><strong><a name="item_taktuk_3a_3aefclsd">TakTuk::EFCLSD</a></strong>
<dd>
<p>the communication channel to the <strong>TakTuk</strong> engine has been closed. This
typically occur when shutting down the logical network (using Ctrl-C on root
node for instance).</p>
</dd>
</li>
<dt><strong><a name="item_esread">TakTuk::ESREAD (<code>TakTuk::recv</code> only)</a></strong>
<dd>
<p>a call to <code>sysread</code> failed (the code should be accessible using <code>$!</code>).</p>
</dd>
</li>
<dt><strong><a name="item_eargto">TakTuk::EARGTO (<code>TakTuk::send</code> only)</a></strong>
<dd>
<p><code>to</code> field missing in the arguments.</p>
</dd>
</li>
<dt><strong><a name="item_eargbd">TakTuk::EARGBD (<code>TakTuk::send</code> only)</a></strong>
<dd>
<p><code>body</code> field missing in the arguments.</p>
</dd>
</li>
<dt><strong><a name="item_etmout">TakTuk::ETMOUT (<code>TakTuk::recv</code> only)</a></strong>
<dd>
<p>The call to <code>TakTuk::recv</code> timeouted. This only occur when giving a <code>timeout</code>
field as <code>TakTuk::recv</code> argument.</p>
</dd>
</li>
</dl>
<p>Finally, the <strong>TakTuk</strong> Perl module defines some constants which value match the
different states reported by the stream <code>state</code> (see <code>taktuk(1)</code> for details
about this stream). These constant are the following:</p>
<pre>
TakTuk::TAKTUK_READY
TakTuk::TAKTUK_NUMBERED
TakTuk::TAKTUK_TERMINATED
TakTuk::CONNECTION_FAILED
TakTuk::CONNECTION_INITIALIZED
TakTuk::CONNECTION_LOST
TakTuk::COMMAND_STARTED
TakTuk::COMMAND_FAILED
TakTuk::COMMAND_TERMINATED
TakTuk::UPDATE_FAILED
TakTuk::PIPE_STARTED
TakTuk::PIPE_FAILED
TakTuk::PIPE_TERMINATED
TakTuk::FILE_RECEPTION_STARTED
TakTuk::FILE_RECEPTION_FAILED
TakTuk::FILE_RECEPTION_TERMINATED
TakTuk::FILE_SEND_FAILED
TakTuk::INVALID_TARGET
TakTuk::NO_TARGET
TakTuk::MESSAGE_DELIVERED
TakTuk::INVALID_DESTINATION
TakTuk::UNAVAILABLE_DESTINATION</pre>
<p>
</p>
<hr />
<h1><a name="see_also">SEE ALSO</a></h1>
<p><code>tatkuk(1)</code>, <code>taktukcomm(3)</code>, <code>TakTuk::Pilot(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>
