TakTukComm - Interface to taktuk(1)
communication facilities
$taktuk::error; taktuk::error_msg($);
taktuk::send(%); taktuk::recv(%);
#include <taktuk.h>
extern int taktuk_error;
char *taktuk_error_msg(int msg_code); int taktuk_send(char *dest, const void *buffer, size_t length); int taktuk_recv(char *from, void *buffer, size_t length, int timeout); int taktuk_sendv(char *dest, const struct iovec *iov, int iovcnt); int taktuk_recvv(char *from, const struct iovec *iov, int iovcnt, int timeout);
The TakTuk communication layer interfaces provide a way for programs
executed using the taktuk(1)
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.
WARNING: the TakTuk 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 TakTuk versions.
The Perl communication interface for TakTuk is made of two functions that
can be called by scripts executed using the taktuk_perl
command of
TakTuk or using the TakTuk package provided with the TakTuk
distribution.
These two functions are:
taktuk(1)
for
informations about set specifications).
The two mandatory fields in the arguments are to
(with a set specification)
and body
. Returns an undefined value upon error.
timeout
argument with a numeric value.
Returns an empty list upon error.
When an error occur, both of 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::syswrite
failed. This is due to a syswrite
error
different than EAGAIN
. The code should be accessible using errno
.
taktuk::recv
only)sysread
failed (the code should be accessible using errno
).
taktuk::send
only)to
field missing in the arguments.
taktuk::send
only)body
field missing in the arguments.
taktuk::recv
only)taktuk::recv
timeouted. This only occur when giving a timeout
field as taktuk::recv
argument.
taktuk::send
only)taktuk::send
function is
not correct.
The C communication interface for TakTuk is very similar in its use to
read(2)
, readv(2)
, write(2)
, writev(2)
functions.
Any program using TakTuk C communication interface has to link his program
to the taktuk
and pthread
libraries (the taktuk
library is provided
with the distribution).
Headers of communication functions and constants definitions can be found in
taktuk.h
also provided with the distribution.
The communication functions are:
buffer
made of length
bytes to dest
. dest
might be a single peer or a set specification (see taktuk(1)
for
informations about set specifications). In both cases it should contain
a nul terminated characters string.
Returns the number of bytes written or -1 upon error.
from
to the string that represents the logical number of the sender,
buffer
to the data received up to length
bytes.
If timeout is non nul, taktuk_recv()
might receive a timeout notification.
In this case or in case of error, taktuk_recv()
returns -1.
taktuk_send()
and taktuk_recv()
except
that the trasmitted data is contained in a vector as in readv(2)
or
writev(2)
.
WARNING: for these function the vector of taktuk_recvv
must have the same size
as the vector of taktuk_sendv
otherwise the reception might either block or
cause memory errors. This might be fixed in the future (but not for sure as
the fix would involve some costly operations and does not seem necessary).
When an error occur, all of 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 :
write(2)
failed.
The code should be accessible using errno
.
read(2)
failed.
The code should be accessible using errno
.
taktuk_recv()
(or its vectorized equivalent) timeouted.
This only occur when giving a non nul timeout
value to taktuk_recv()
.
tatkuk(1)
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 perl version and current maintainer of the package is Guillaume Huard.
The taktukcomm
communication interface library is provided under the terms
of the GNU General Public License version 2 or later.