Linux Certif

Toute la documentation sur la certification Linux LPI

taktukcomm

NAME

TakTukComm - Interface to taktuk(1) communication facilities

SYNOPSIS

Perl interface:

   $taktuk::error;
   taktuk::error_msg($);
 
   taktuk::get($);
 
   taktuk::send(%);
   taktuk::recv(%);
 
 

C interface:

   #include <taktuk.h>
 
   const char *taktuk_error_msg(int msg_code);
 
   int taktuk_init_threads();
   int taktuk_leave_threads();
 
   int taktuk_get(char *field, long *value);
 
   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);
 
   int taktuk_send(long dest, const void *buffer, size_t length);
   int taktuk_sendv(long dest, const struct iovec *iov, int iovcnt);
 
   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);
 
   int taktuk_wait_message(long *from, size_t *size, int timeout);
 
   int taktuk_read ( void *buffer, size_t length );
   int taktuk_readv( const struct iovec *iov, int iovcnt );
 
 

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::get($);

gets some information from TakTuk. 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.

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

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:

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.

int taktuk_get(char *field, long *result);

gets some information from TakTuk 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.

multicast send functions

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);

"taktuk_multi_send" sends the content of "buffer" made of "length" bytes to the set of target destinations "dest" (nul terminated characters string, see taktuk(1) for informations about set specifications). "taktuk_multi_sendv" is the vector variant of "taktuk_multi_send" (similar to "writev" system function).

single host send/recv functions

int taktuk_send(long dest, const void *buffer, size_t length);

int taktuk_sendv(long dest, const struct iovec *iov, int iovcnt);

sends the content of "buffer" made of "length" bytes to "dest". "taktuk_sendv" is the vector variant of "taktuk_send" (similar to "writev" system function).

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);

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 non nul, "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(long* from, size_t *size, int 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 nul 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 :

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)

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.