taktuk - Interface library to "taktuk(1)" communication facilities

       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.

perl v5.38.2                                       2024-04-01                                          TAKTUK(3)

       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:

   miscellaneousfunctionsinttaktuk_init_threads();inttaktuk_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).

       inttaktuk_get(constchar*field,unsignedlong*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.

   multicastsendfunctionsinttaktuk_multi_send(constchar*dest,constchar*target,constvoid*buffer,size_tlength);inttaktuk_multi_sendv(constchar*dest,constchar*target,conststructiovec*iov,intiovcnt);
           "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).

   singlehostsend/recvfunctionsinttaktuk_send(unsignedlongdest,unsignedlongtarget,constvoid*buffer,size_tlength);inttaktuk_sendv(unsignedlongdest,unsignedlongtarget,conststructiovec*iov,intiovcnt);
           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).

       inttaktuk_recv(unsignedlong*from,void*buffer,size_t*length,structtimeval*timeout);inttaktuk_recvv(unsignedlong*from,conststructiovec*iov,intiovcnt,structtimeval*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-levelrecvfunctionsinttaktuk_wait_message(unsignedlong*from,size_t*size,structtimeval*timeout);inttaktuk_read(void*buffer,size_tlength);inttaktuk_readv(conststructiovec*iov,intiovcnt);
           "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".

       taktuk - Interface library to "taktuk(1)" communication facilities

       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".

tatkuk(1), TakTuk(3), TakTuk::Pilot(3)

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