TakTuk(3pm)						User Contributed Perl Documentation					       TakTuk(3pm)

NAME

       TakTuk - Perl module that provides an interface to "taktuk(1)" communication facilities

SYNOPSIS

	 use TakTuk;

	 my $rank = TakTuk::get('rank');
	 my $count = TakTuk::get('count');

	 print "I'm process $rank among $count
";

	 if ($rank > 1) {
	     my ($from, $message) = TakTuk::recv();
	     if (not defined($message)) {
		 print "Trying to recv: ",
		       TakTuk::error_msg($TakTuk::error), "
";
	     } else {
		 print "$rank received $message from $from
";
	     }
	 }

	 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), "
";
	 }

	 if ($rank == 1) {
	     my ($from, $message) = TakTuk::recv(timeout=>5);
	     if (not defined($message)) {
		 print "Trying to recv :",
		       TakTuk::error_msg($TakTuk::error), "
";
	     } else {
		 print "$rank received $message from $from
";
	     }
	 }

DESCRIPTION

       The TakTuk communication layer Perl interface provides a way for programs executed using the taktuk(1) 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.

       The Perl communication interface for TakTuk is made of functions that can be called by scripts executed using the "taktuk_perl" command of
       the TakTuk engine (preferred way, less installation requirements on remote machines) or using the TakTuk Perl module provided with the
       TakTuk distribution.  These functions are:

       TakTuk::get($)
	   gets some information from TakTuk. Currently available information includes 'target', 'rank', 'count', 'father', 'child_min' and
	   'child_max'. This is a better way to get this information than environment variables as its takes into account renumbering that might
	   occur after process spawn.

       TakTuk::send(%)
	   sends a scalar to a single peer or a set specification (see taktuk(1) for information about set specifications).  The two mandatory
	   fields in the arguments are "to" (with a set specification) and "body". Optionally, a field "target" might be given. Returns an
	   undefined value upon error.

       TakTuk::recv(%)
	   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 "timeout" argument with a numeric value.  Returns an empty list upon error.

       When an error occur, all these functions set the variable $TakTuk::error to the numeric code of the error that occured. A textual
       description of the error is provided by the function TakTuk::error_msg($) that takes the error code as an argument.

       Error codes are the following :

       TakTuk::ESWRIT
	   a call to "TakTuk::syswrite" failed. This is due to a "syswrite" error different than "EAGAIN". The code should be accessible using $!.

       TakTuk::EFCLSD
	   the communication channel to the TakTuk engine has been closed. This typically occur when shutting down the logical network (using
	   Ctrl-C on root node for instance).

       TakTuk::ESREAD ("TakTuk::recv" only)
	   a call to "sysread" failed (the code should be accessible using $!).

       TakTuk::EARGTO ("TakTuk::send" only)
	   "to" field missing in the arguments.

       TakTuk::EARGBD ("TakTuk::send" only)
	   "body" field missing in the arguments.

       TakTuk::ETMOUT ("TakTuk::recv" only)
	   The call to "TakTuk::recv" timeouted. This only occur when giving a "timeout" field as "TakTuk::recv" argument.

       Finally, the TakTuk Perl module defines some constants which value match the different states reported by the stream "state" (see taktuk(1)
       for details about this stream). These constant are the following:

	 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

SEE ALSO

       tatkuk(1), taktukcomm(3), TakTuk::Pilot(3)

AUTHOR

       The original concept of TakTuk 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.

       The author of the version 3 (perl version) and current maintainer of the package is Guillaume Huard.

COPYRIGHT

       The "TakTuk" communication interface library is provided under the terms of the GNU General Public License version 2 or later.

perl v5.14.2							    2012-06-11							       TakTuk(3pm)