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 which 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 occurred.

       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.