<?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>