taktuk - Interface library to taktuk(1) communication facilities
#include <taktuk.h>
const char *taktuk_error_msg(int msg_code);
int taktuk_init_threads(); int taktuk_leave_threads();
int taktuk_get(const char *field, unsigned long *result);
int taktuk_multi_send(const char *dest, const char *target,
const void *buffer, size_t length);
int taktuk_multi_sendv(const char *dest, const char *target,
const struct iovec *iov, int iovcnt);
int taktuk_send(unsigned long dest, unsigned long target,
const void *buffer, size_t length);
int taktuk_sendv(unsigned long dest, unsigned long target,
const struct iovec *iov, int iovcnt);
int taktuk_recv(unsigned long *from, void *buffer, size_t *length,
struct timeval *timeout);
int taktuk_recvv(unsigned long *from, const struct iovec *iov,
int iovcnt, struct timeval *timeout);
int taktuk_wait_message(unsigned long *from, size_t *size,
struct timeval *timeout);
int taktuk_read( void *buffer, size_t length ); int taktuk_readv( const struct iovec *iov, int iovcnt );
The TakTuk communication layer interface library 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.
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 for communication functions and constants definitions can be found in
taktuk.h also provided with the distribution.
The communication functions are:
functions to be called once in the process respectively before threads creation and after threads destruction if you want TakTuk C interface to be thread-safe.
Nevertheless, notice that, because of the way TakTuk is implemented, the
handling of recv functions in several threads is completely sequentialized.
This is especially important regarding timeouts: if a timeout is given to a
recv function, it will only be started at the calling thread's turn. In
other words, issuing multiple timeouted recv in several threads of the same
process might result in timeouts longer that expected (they become at most the
sum of all pending recv timeouts).
gets some information from TakTuk and places it into result. Currently available information are "target", "rank", "count", "father", "child_min" and "child_max". This is a better way to get these information than environment variables as its takes into account renumbering that might occur after process spawn.
taktuk_multi_send sends the content of buffer made of length bytes to
the set of target processes target present on the set of destinations
dest (nul terminated characters strings, see taktuk(1) for information
about set specifications for destination hosts and target processes).
taktuk_multi_sendv is the vector variant of taktuk_multi_send (similar to
writev system function).
sends the content of buffer made of length bytes to process target on
the host dest (see taktuk(1) for more information about target
processes). In this case, the target value might also be
TAKTUK_TARGET_ANY to target the first process performing a recv,
TAKTUK_TARGET_ALL to target all processes, or TAKTUK_TARGET_OUTPUT to target
the message stream rather than a process. taktuk_sendv is the vector
variant of taktuk_send (similar to writev system function).
blocks until the reception of a message. If a regular message is received,
taktuk_recv sets the value of its arguments: from to the logical number
of the sender, buffer to the data received wich is made of
length bytes. If timeout is not NULL, taktuk_recv() might receive a
timeout notification. In this case, taktuk_recv() returns the TAKTUK_ETMOUT
error code.
taktuk_recvv is the vector variant of taktuk_recv (similar to
readv system function).
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.
taktuk_wait_message waits for a taktuk message to be available and sets
from to the logical number of the sender and size to the size of the
received message.
It must be followed by a call to either taktuk_read or taktuk_readv to
read the data (using the size given by taktuk_wait_message).
As other TakTuk receive functions, this function might return the
TAKTUK_ETMOUT error code if timeout is not NULL and expires before the
reception.
If you don't know in advance the size of the data being sent to you, you can
use these lower level functions. Actually, taktuk_recv is equivalent to a
call to taktuk_wait_message followed by errors checks on buffer size and a
call to taktuk_read. This is the same for taktuk_recvv.
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
taktuk_error_msg() that takes the error code as an argument.
Error codes are the following :
a call to write(2) failed. The code should be accessible using errno.
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).
a call to read(2) failed. The code should be accessible using errno.
The call to taktuk_recv() (or its vectorized equivalent) or to
taktuk_wait_message timeouted. This only occur when giving a non nul
timeout value to these functions.
An internal memory allocation failure occured.
A buffer of incorrect size has been given to store all the data read by a receive function.
The connector communication channels have not been found. This typically occur when launching a TakTuk program without using TakTuk.
The field given to taktuk_get is not a valid TakTuk field.
No memory to allocate a new mutex
Resources temporarily unavailable for new mutex allocation.
Other error codes are internal TakTuk errors which should strongly suggest a
bug in TakTuk. They have also a textual description that is returned by
taktuk_error_msg.
tatkuk(1), TakTuk(3), TakTuk::Pilot(3)
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.
The taktukcomm communication interface library is provided under the terms
of the GNU General Public License version 2 or later.