<!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>
<link rev="made" href="mailto:root@b07.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="#perl_interface">PERL INTERFACE</a></li>
<li><a href="#c_interface">C INTERFACE</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>TakTukComm - Interface to <code>taktuk(1)</code> communication facilities</p>
<p>
</p>
<hr />
<h1><a name="synopsis">SYNOPSIS</a></h1>
<p><strong>Perl interface:</strong></p>
<pre>
$taktuk::error;
taktuk::error_msg($);</pre>
<pre>
taktuk::get($);</pre>
<pre>
taktuk::send(%);
taktuk::recv(%);</pre>
<p><strong>C interface:</strong></p>
<pre>
#include <taktuk.h></pre>
<pre>
const char *taktuk_error_msg(int msg_code);</pre>
<pre>
int taktuk_init_threads();
int taktuk_leave_threads();</pre>
<pre>
int taktuk_get(char *field, long *value);</pre>
<pre>
int taktuk_multi_send(const char *dest, const void *buffer,
size_t length);
int taktuk_multi_sendv(const char *dest, const struct iovec *iov,
int iovcnt);</pre>
<pre>
int taktuk_send(long dest, const void *buffer, size_t length);
int taktuk_sendv(long dest, const struct iovec *iov, int iovcnt);</pre>
<pre>
int taktuk_recv(long *from, void *buffer, size_t *length, int timeout);
int taktuk_recvv(long *from, const struct iovec *iov, int iovcnt,
int timeout);</pre>
<pre>
int taktuk_wait_message(long *from, size_t *size, int timeout);</pre>
<pre>
int taktuk_read ( void *buffer, size_t length );
int taktuk_readv( const struct iovec *iov, int iovcnt );</pre>
<p>
</p>
<hr />
<h1><a name="description">DESCRIPTION</a></h1>
<p>The <strong>TakTuk</strong> communication layer interfaces provide a way for programs
executed using the <code>taktuk(1)</code> 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. This interface
is available both for the Perl and the C langages.</p>
<p>WARNING: the <strong>TakTuk</strong> communication interface is not process-safe : it is
probably a very bad idea to use point-to-point communication in
more than one process related to a single logical peer (these processes might
be several local commands or forked processes). Nevertheless, the C interface
is thread-safe (it uses posix mutexes in its critical sections). These issues
are likely to be addressed in future <strong>TakTuk</strong> versions.</p>
<p>
</p>
<hr />
<h1><a name="perl_interface">PERL INTERFACE</a></h1>
<p>The Perl communication interface for <strong>TakTuk</strong> is made of two functions that
can be called by scripts executed using the <code>taktuk_perl</code> command of
<strong>TakTuk</strong> or using the <strong>TakTuk</strong> package provided with the <strong>TakTuk</strong>
distribution.
These two functions are:</p>
<dl>
<dt><strong><a name="item_get"><strong>taktuk::get($);</strong></a></strong><br />
</dt>
<dd>
gets some information from <strong>TakTuk</strong>. Currently available informations are
'rank' and 'count'. This is a better way to get these informations than
environment variables as its takes into account renumbering that might occur
after process spawn.
</dd>
<p></p>
<dt><strong><a name="item_send"><strong>taktuk::send(%);</strong></a></strong><br />
</dt>
<dd>
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>. Returns an undefined value upon error.
</dd>
<p></p>
<dt><strong><a name="item_recv"><strong>taktuk::recv(%);</strong></a></strong><br />
</dt>
<dd>
blocks until the reception of a message. Returns a list of three elements: the
logical number of the destination of the message, the logical number of its
source and the message itself.
Accepts an optional <code>timeout</code> argument with a numeric value.
Returns an empty list upon error.
</dd>
<p></p></dl>
<p>When an error occur, both of 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><br />
</dt>
<dd>
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>errno</code>.
</dd>
<p></p>
<dt><strong><a name="item_taktuk_3a_3aefclsd">taktuk::EFCLSD</a></strong><br />
</dt>
<dd>
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).
</dd>
<p></p>
<dt><strong><a name="item_esread">taktuk::ESREAD (<code>taktuk::recv</code> only)</a></strong><br />
</dt>
<dd>
a call to <code>sysread</code> failed (the code should be accessible using <code>errno</code>).
</dd>
<p></p>
<dt><strong><a name="item_eargto">taktuk::EARGTO (<code>taktuk::send</code> only)</a></strong><br />
</dt>
<dd>
<code>to</code> field missing in the arguments.
</dd>
<p></p>
<dt><strong><a name="item_eargbd">taktuk::EARGBD (<code>taktuk::send</code> only)</a></strong><br />
</dt>
<dd>
<code>body</code> field missing in the arguments.
</dd>
<p></p>
<dt><strong><a name="item_etmout">taktuk::ETMOUT (<code>taktuk::recv</code> only)</a></strong><br />
</dt>
<dd>
The call to <code>taktuk::recv</code> timeouted. This only occur when giving a <code>timeout</code>
field as <code>taktuk::recv</code> argument.
</dd>
<p></p>
<dt><strong><a name="item_einvst">taktuk::EINVST (<code>taktuk::send</code> only)</a></strong><br />
</dt>
<dd>
The set specification given as a destination to the <code>taktuk::send</code> function is
not correct.
</dd>
<p></p></dl>
<p>
</p>
<hr />
<h1><a name="c_interface">C INTERFACE</a></h1>
<p>Any program using <strong>TakTuk</strong> C communication interface has to link his program
to the <code>taktuk</code> and <code>pthread</code> libraries (the <code>taktuk</code> library is provided
with the distribution).
Headers of communication functions and constants definitions can be found in
<code>taktuk.h</code> also provided with the distribution.</p>
<p>The communication functions are:</p>
<p><strong>miscellaneous functions</strong></p>
<dl>
<dt><strong><a name="item_taktuk_init_threads">int taktuk_init_threads();</a></strong><br />
</dt>
<dt><strong><a name="item_taktuk_leave_threads">int taktuk_leave_threads();</a></strong><br />
</dt>
<dd>
functions to be called once in the process respectively before threads creation
and after threads destruction if you want <strong>TakTuk</strong> C interface to be
thread-safe.
</dd>
<p></p>
<dt><strong><a name="item_taktuk_get">int taktuk_get(char *field, long *result);</a></strong><br />
</dt>
<dd>
gets some information from <strong>TakTuk</strong> and places it into result. Currently
available informations are ``rank'' and ``count''. This is a better way to get
these informations than environment variables as its takes into account
renumbering that might occur after process spawn.
</dd>
<p></p></dl>
<p><strong>multicast send functions</strong></p>
<dl>
<dt><strong><a name="item_taktuk_multi_send">int taktuk_multi_send(const char *dest, const void *buffer, size_t length);</a></strong><br />
</dt>
<dt><strong><a name="item_taktuk_multi_sendv">int taktuk_multi_sendv(const char *dest, const struct iovec *iov, int iovcnt);</a></strong><br />
</dt>
<dd>
<a href="#item_taktuk_multi_send"><code>taktuk_multi_send</code></a> sends the content of <code>buffer</code> made of <code>length</code> bytes to
the set of target destinations <code>dest</code> (nul terminated characters string, see
<code>taktuk(1)</code> for informations about set specifications).
<a href="#item_taktuk_multi_sendv"><code>taktuk_multi_sendv</code></a> is the vector variant of <a href="#item_taktuk_multi_send"><code>taktuk_multi_send</code></a> (similar to
<code>writev</code> system function).
</dd>
<p></p></dl>
<p><strong>single host send/recv functions</strong></p>
<dl>
<dt><strong><a name="item_taktuk_send">int taktuk_send(long dest, const void *buffer, size_t length);</a></strong><br />
</dt>
<dt><strong><a name="item_taktuk_sendv">int taktuk_sendv(long dest, const struct iovec *iov, int iovcnt);</a></strong><br />
</dt>
<dd>
sends the content of <code>buffer</code> made of <code>length</code> bytes to <code>dest</code>.
<a href="#item_taktuk_sendv"><code>taktuk_sendv</code></a> is the vector variant of <a href="#item_taktuk_send"><code>taktuk_send</code></a> (similar to
<code>writev</code> system function).
</dd>
<p></p>
<dt><strong><a name="item_taktuk_recv">int taktuk_recv(long *from, void *buffer, size_t *length, int timeout);</a></strong><br />
</dt>
<dt><strong><a name="item_taktuk_recvv">int taktuk_recvv(long *from, const struct iovec *iov, int iovcnt, int timeout);</a></strong><br />
</dt>
<dd>
blocks until the reception of a message. If a regular message is received,
<a href="#item_taktuk_recv"><code>taktuk_recv</code></a> sets the value of its arguments: <code>from</code> to the logical number
of the sender, <code>buffer</code> to the data received wich is made of
<code>length</code> bytes. If timeout is non nul, <a href="#item_taktuk_recv"><code>taktuk_recv()</code></a> might receive a
timeout notification. In this case, <a href="#item_taktuk_recv"><code>taktuk_recv()</code></a> returns the TAKTUK_ETMOUT
error code.
<a href="#item_taktuk_recvv"><code>taktuk_recvv</code></a> is the vector variant of <a href="#item_taktuk_recv"><code>taktuk_recv</code></a> (similar to
<code>readv</code> system function).
</dd>
<dd>
<p>WARNING: the buffer size should be sufficient to receive all the data of the
matching send. If this is not the case, the program is likely to end up
abruptly with a segmentation fault.</p>
</dd>
<p></p></dl>
<p><strong>low-level recv functions</strong></p>
<dl>
<dt><strong><a name="item_taktuk_wait_message">int taktuk_wait_message(long* from, size_t *size, int timeout);</a></strong><br />
</dt>
<dt><strong><a name="item_taktuk_read">int taktuk_read (void* buffer, size_t length);</a></strong><br />
</dt>
<dt><strong><a name="item_taktuk_readv">int taktuk_readv(const struct iovec *iov, int iovcnt);</a></strong><br />
</dt>
<dd>
<a href="#item_taktuk_wait_message"><code>taktuk_wait_message</code></a> waits for a taktuk message to be available and sets
<code>from</code> to the logical number of the sender and <code>size</code> to the size of the
received message.
It must be followed by a call to either <a href="#item_taktuk_read"><code>taktuk_read</code></a> or <a href="#item_taktuk_readv"><code>taktuk_readv</code></a> to
read the data (using the size given by <a href="#item_taktuk_wait_message"><code>taktuk_wait_message</code></a>).
As other <strong>TakTuk</strong> receive functions, this function might return the
TAKTUK_ETMOUT error code if <code>timeout</code> is not nul and expires before the
reception.
</dd>
<dd>
<p>If you don't know in advance the size of the data being sent to you, you can
use these lower level functions. Actually, <a href="#item_taktuk_recv"><code>taktuk_recv</code></a> is equivalent to a
call to <a href="#item_taktuk_wait_message"><code>taktuk_wait_message</code></a> followed by errors checks on buffer size and a
call to <a href="#item_taktuk_read"><code>taktuk_read</code></a>. This is the same for <a href="#item_taktuk_recvv"><code>taktuk_recvv</code></a>.</p>
</dd>
<p></p></dl>
<p>When an error occur, all of these functions return one of the following numeric
error code. 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_eswrit">TAKTUK_ESWRIT</a></strong><br />
</dt>
<dd>
a call to <code>write(2)</code> failed. The code should be accessible using <code>errno</code>.
</dd>
<p></p>
<dt><strong><a name="item_taktuk_efclsd">TAKTUK_EFCLSD</a></strong><br />
</dt>
<dd>
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).
</dd>
<p></p>
<dt><strong><a name="item_taktuk_esread">TAKTUK_ESREAD (receives only)</a></strong><br />
</dt>
<dd>
a call to <code>read(2)</code> failed. The code should be accessible using <code>errno</code>.
</dd>
<p></p>
<dt><strong><a name="item_taktuk_etmout">TAKTUK_ETMOUT (receives only)</a></strong><br />
</dt>
<dd>
The call to <a href="#item_taktuk_recv"><code>taktuk_recv()</code></a> (or its vectorized equivalent) or to
<a href="#item_taktuk_wait_message"><code>taktuk_wait_message</code></a> timeouted. This only occur when giving a non nul
<code>timeout</code> value to these functions.
</dd>
<p></p>
<dt><strong><a name="item_taktuk_ealloc">TAKTUK_EALLOC</a></strong><br />
</dt>
<dd>
An internal memory allocation failure occured.
</dd>
<p></p>
<dt><strong><a name="item_taktuk_eibuff">TAKTUK_EIBUFF</a></strong><br />
</dt>
<dd>
A buffer of incorrect size has been given to store all the data read by a
receive function.
</dd>
<p></p>
<dt><strong><a name="item_taktuk_enocon">TAKTUK_ENOCON</a></strong><br />
</dt>
<dd>
The connector communication channels have not been found. This typically occur
when launching a <strong>TakTuk</strong> program without using <strong>TakTuk</strong>.
</dd>
<p></p>
<dt><strong><a name="item_taktuk_einval">TAKTUK_EINVAL (get only)</a></strong><br />
</dt>
<dd>
The field given to <a href="#item_taktuk_get"><code>taktuk_get</code></a> is not a valid <strong>TakTuk</strong> field.
</dd>
<p></p>
<dt><strong><a name="item_taktuk_emtxnm">TAKTUK_EMTXNM (init threads only)</a></strong><br />
</dt>
<dd>
No memory to allocate a new mutex
</dd>
<p></p>
<dt><strong><a name="item_taktuk_emtxag">TAKTUK_EMTXAG (init threads only)</a></strong><br />
</dt>
<dd>
Resources temporarily unavailable for new mutex allocation.
</dd>
<p></p></dl>
<p>Other error codes are internal <strong>TakTuk</strong> errors which should strongly suggest a
bug in <strong>TakTuk</strong>. They have also a textual description that is returned by
<code>taktuk_error_msg</code>.</p>
<p>
</p>
<hr />
<h1><a name="see_also">SEE ALSO</a></h1>
<p><code>tatkuk(1)</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>taktukcomm</code> communication interface library is provided under the terms
of the GNU General Public License version 2 or later.</p>
</body>
</html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
d26322ea661b980920bc5858961a72ee
>
files
>
11
