--- name: "taktukcomm" section: "3" platform: "linux" package: "libtaktuk-1-dev" version: "3.7.7-3.1+b1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/taktukcomm" --- # taktukcomm(3) Interface library to "taktuk(1)" communication facilities ## NAME taktuk - Interface library to "[taktuk(1)](/taktuk/1.md)" communication facilities ## SYNOPSIS ``` #include 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.