NAME¶
taktuk - Interface library to "
taktuk(1)" communication facilities
SYNOPSIS¶
#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 );
DESCRIPTION¶
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:
miscellaneous functions¶
- int taktuk_init_threads();
- int taktuk_leave_threads();
- 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).
- int taktuk_get(const char *field, unsigned long
*result);
- 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.
multicast send functions¶
- 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);
- "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).
single host send/recv functions¶
- 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);
- 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).
- 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);
- 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.
low-level recv functions¶
- 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);
- "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".
RETURN VALUE¶
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 :
- 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) or to "taktuk_wait_message" timeouted. This only
occur when giving a non nul "timeout" value to these
functions.
- TAKTUK_EALLOC
- An internal memory allocation failure occured.
- TAKTUK_EIBUFF
- A buffer of incorrect size has been given to store all the
data read by a receive function.
- TAKTUK_ENOCON
- The connector communication channels have not been found.
This typically occur when launching a TakTuk program without using
TakTuk.
- TAKTUK_EINVAL (get only)
- The field given to "taktuk_get" is not a valid
TakTuk field.
- TAKTUK_EMTXNM (init threads only)
- No memory to allocate a new mutex
- TAKTUK_EMTXAG (init threads only)
- 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".
SEE ALSO¶
tatkuk(1),
TakTuk(3), TakTuk::Pilot(3)
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 version 3 (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.