.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "TakTuk 3pm"
.TH TakTuk 3pm "2019-07-18" "perl v5.28.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
TakTuk \- Perl module that provides an interface to "taktuk(1)" communication
facilities
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use TakTuk;
\&  
\&  my $rank = TakTuk::get(\*(Aqrank\*(Aq);
\&  my $count = TakTuk::get(\*(Aqcount\*(Aq);
\&  
\&  print "I\*(Aqm process $rank among $count\en";
\&  
\&  if ($rank > 1) {
\&      my ($from, $message) = TakTuk::recv();
\&      if (not defined($message)) {
\&          print "Trying to recv: ",
\&                TakTuk::error_msg($TakTuk::error), "\en";
\&      } else {
\&          print "$rank received $message from $from\en";
\&      }
\&  }
\&  
\&  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), "\en";
\&  }
\&  
\&  if ($rank == 1) {
\&      my ($from, $message) = TakTuk::recv(timeout=>5);
\&      if (not defined($message)) {
\&          print "Trying to recv :",
\&                TakTuk::error_msg($TakTuk::error), "\en";
\&      } else {
\&          print "$rank received $message from $from\en";
\&      }
\&  }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \fBTakTuk\fR communication layer Perl interface provides a way for programs
executed using the \f(CWtaktuk(1)\fR 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.
.PP
The Perl communication interface for \fBTakTuk\fR is made of functions that can be
called by scripts executed using the \f(CW\*(C`taktuk_perl\*(C'\fR command of the \fBTakTuk\fR
engine (preferred way, less installation requirements on remote machines) or
using the \fBTakTuk\fR Perl module provided with the \fBTakTuk\fR distribution.
These functions are:
.IP "\fBTakTuk::get($)\fR" 4
.IX Item "TakTuk::get($)"
gets some information from \fBTakTuk\fR. 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.
.IP "\fBTakTuk::send(%)\fR" 4
.IX Item "TakTuk::send(%)"
sends a scalar to a single peer or a set specification (see \f(CWtaktuk(1)\fR for
information about set specifications).  The two mandatory fields in the
arguments are \f(CW\*(C`to\*(C'\fR (with a set specification) and \f(CW\*(C`body\*(C'\fR. Optionally, a field
\&\f(CW\*(C`target\*(C'\fR might be given. Returns an undefined value upon error.
.IP "\fBTakTuk::recv(%)\fR" 4
.IX Item "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 \f(CW\*(C`timeout\*(C'\fR argument with a numeric value.
Returns an empty list upon error.
.PP
When an error occur, all these functions set the variable \f(CW$TakTuk::error\fR
to the numeric code of the error that occurred. A textual description of the
error is provided by the function \f(CWTakTuk::error_msg($)\fR that takes the error
code as an argument.
.PP
Error codes are the following :
.IP "TakTuk::ESWRIT" 4
.IX Item "TakTuk::ESWRIT"
a call to \f(CW\*(C`TakTuk::syswrite\*(C'\fR failed. This is due to a \f(CW\*(C`syswrite\*(C'\fR error
different than \f(CW\*(C`EAGAIN\*(C'\fR. The code should be accessible using \f(CW$!\fR.
.IP "TakTuk::EFCLSD" 4
.IX Item "TakTuk::EFCLSD"
the communication channel to the \fBTakTuk\fR engine has been closed. This
typically occur when shutting down the logical network (using Ctrl-C on root
node for instance).
.ie n .IP "TakTuk::ESREAD (""TakTuk::recv"" only)" 4
.el .IP "TakTuk::ESREAD (\f(CWTakTuk::recv\fR only)" 4
.IX Item "TakTuk::ESREAD (TakTuk::recv only)"
a call to \f(CW\*(C`sysread\*(C'\fR failed (the code should be accessible using \f(CW$!\fR).
.ie n .IP "TakTuk::EARGTO (""TakTuk::send"" only)" 4
.el .IP "TakTuk::EARGTO (\f(CWTakTuk::send\fR only)" 4
.IX Item "TakTuk::EARGTO (TakTuk::send only)"
\&\f(CW\*(C`to\*(C'\fR field missing in the arguments.
.ie n .IP "TakTuk::EARGBD (""TakTuk::send"" only)" 4
.el .IP "TakTuk::EARGBD (\f(CWTakTuk::send\fR only)" 4
.IX Item "TakTuk::EARGBD (TakTuk::send only)"
\&\f(CW\*(C`body\*(C'\fR field missing in the arguments.
.ie n .IP "TakTuk::ETMOUT (""TakTuk::recv"" only)" 4
.el .IP "TakTuk::ETMOUT (\f(CWTakTuk::recv\fR only)" 4
.IX Item "TakTuk::ETMOUT (TakTuk::recv only)"
The call to \f(CW\*(C`TakTuk::recv\*(C'\fR timeouted. This only occur when giving a \f(CW\*(C`timeout\*(C'\fR
field as \f(CW\*(C`TakTuk::recv\*(C'\fR argument.
.PP
Finally, the \fBTakTuk\fR Perl module defines some constants which value match the
different states reported by the stream \f(CW\*(C`state\*(C'\fR (see \f(CWtaktuk(1)\fR for details
about this stream). These constant are the following:
.PP
.Vb 10
\&  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
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\f(CWtatkuk(1)\fR, \f(CWtaktukcomm(3)\fR, \f(CWTakTuk::Pilot(3)\fR
.SH "AUTHOR"
.IX Header "AUTHOR"
The original concept of \fBTakTuk\fR 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.
.PP
The author of the version 3 (perl version) and current maintainer of the package is Guillaume Huard.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
The \f(CW\*(C`TakTuk\*(C'\fR communication interface library is provided under the terms
of the \s-1GNU\s0 General Public License version 2 or later.