USER MANUAL


NAME

TakTukComm - Interface to taktuk(1) communication facilities


SYNOPSIS

Perl interface:
  $taktuk::error;
  taktuk::error_msg($);
  taktuk::send(%);
  taktuk::recv(%);
C interface:
  #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);


DESCRIPTION

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.


PERL INTERFACE

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::send(%);
sends a scalar to a single peer or a set specification (see 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.

taktuk::recv(%);
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 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::ESWRIT
a call to taktuk::syswrite failed. This is due to a syswrite error different than EAGAIN. The code should be accessible using errno.

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 errno).

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.

taktuk::EINVST (taktuk::send only)
The set specification given as a destination to the taktuk::send function is not correct.


C INTERFACE

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:

int taktuk_send(char *dest, const void *buffer, size_t length);
sends the content of 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.

int taktuk_recv(char *from, void *buffer, size_t length, int timeout);
blocks until the reception of a message. If a regular message is received, returns the number of bytes read and sets the value of its arguments: 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.

int taktuk_sendv(char *dest, const struct iovec *iov, int iovcnt);
int taktuk_recvv(char *from, const struct iovec *iov, int iovcnt, int timeout);
these two functions do the same as 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 :

TAKTUK_ESWRIT
a call to write(2) failed. The code should be accessible using errno.

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 (receives only)
a call to read(2) failed. The code should be accessible using errno.

TAKTUK_ETMOUT (receives only)
The call to taktuk_recv() (or its vectorized equivalent) timeouted. This only occur when giving a non nul timeout value to taktuk_recv().

TAKTUK_EALLOC
An internal memory allocation failure occured.

TAKTUK_EIBUFF
An unsufficient buffer has been given to store all the data.

TAKTUK_EINTRN
An internal error occured. This strongly suggest a bug in TakTuk.


SEE ALSO

tatkuk(1)


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 perl version and current maintainer of the package is Guillaume Huard.


COPYRIGHT

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