TAKTUK(3)

📦
version 3.7.8 · 6 versions
, in ubuntu resolute, ubuntu stonking

💖 TAKTUK(3) — the TakTuk Library Functions Manual, bestie edition 💖

okay so. this is the manual for the TakTuk library functions, aka the C interface to the taktuk(1) communication facilities. it's giving "let me talk to my siblings in the parallel tree" energy and honestly? iconic. 🫶

✨ 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 is literally your way to let programs that are running under the taktuk(1) command swap data with each other. the model is simple: sends that are multicast-like, and receives that can optionally time out. and no cap, it's built as a control facility — so please, do not treat this as a high performance communication library. it's a group chat, not a fiber optic cable. 💅

any program that uses the TakTuk C communication interface has to link itself against the taktuk and pthread libraries (the taktuk library ships with the distribution, don't worry). the headers for the communication functions plus the constant definitions live in taktuk.h, which is also provided with the distribution. 🎀

the communication functions are:

🧚 miscellaneous functions

  • int taktuk_init_threads();
  • int taktuk_leave_threads();

these are the functions you call exactly once in the process — respectively before threads creation and after threads destruction — if you want the TakTuk C interface to be thread-safe.

but bestie, heads up: because of the way TakTuk is implemented, the handling of recv functions across several threads is completely sequentialized. this matters so much for timeouts. if a timeout is handed to a recv function, it will only be started at the calling thread's turn. in other words, issuing multiple timeouted recv calls in several threads of the same process might result in timeouts longer than expected — they become at most the sum of all pending recv timeouts. yeah. math. 😭
  • int taktuk_get(const char *field, unsigned long *result);

grabs some info from TakTuk and drops it into result. right now the available pieces of information are "target", "rank", "count", "father", "child_min" and "child_max". and this is a better way to get these than environment variables, because it takes into account the renumbering that might occur after a process spawn. so like, use this, fr fr. ✨

📣 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. both dest and target are nul terminated character strings — go peek at taktuk(1) for the tea on set specifications for destination hosts and target processes. taktuk_multi_sendv is the vector variant of taktuk_multi_send (similar to the 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 (check taktuk(1) for more about target processes). in this case the target value might also be:

  • TAKTUK_TARGET_ANY — targets the first process performing a recv
  • TAKTUK_TARGET_ALL — targets all the processes
  • TAKTUK_TARGET_OUTPUT — targets the message stream rather than a process

taktuk_sendv is the vector variant of taktuk_send (similar to the 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 a message is received. if a regular message comes in, taktuk_recv sets the values of its arguments: from to the logical number of the sender, and buffer to the data received, which is made of length bytes. if timeout is not NULL, taktuk_recv() might receive a timeout notification. when that happens, taktuk_recv() returns the TAKTUK_ETMOUT error code. taktuk_recvv is the vector variant of taktuk_recv (similar to the readv system function). 💜

⚠️ WARNING: the buffer size should be sufficient to receive all the data of the matching send. if it's not, the program is likely to end up abruptly with a segmentation fault. that's not a vibe, that's a crash. 💀

🍓 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 become 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 actually read the data (using the size that taktuk_wait_message gave you). and just like the other TakTuk receive functions, this one 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, these lower level functions are your besties. fun fact: taktuk_recv is actually equivalent to a call to taktuk_wait_message, followed by error checks on buffer size, followed by a call to taktuk_read. same deal for taktuk_recvv. the way that recursion is just recursion, iykyk. 🔥

💅 RETURN VALUE 💅

when an error occurs, all of these functions return one of the following numeric error codes. a textual description of the error is provided by the function taktuk_error_msg(), which takes the error code as an argument. cute, right?

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 occurs when shutting down the logical network (using Ctrl-C on the root node for instance). rip the connection. 😭
  • 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 occurs 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 occurs when launching a TakTuk program without using TakTuk. not me launching the program without the thing the program needs 🙈
  • 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 also have a textual description that is returned by taktuk_error_msg. so if you see one of those, it's not you, it's TakTuk. 🫶

👀 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. academic slay. 👑

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.

and that's the whole page, bestie! this was perl v5.40.1, dated 2025-09-30, and it's been real. go forth and multicast responsibly. 💖✨🦋

📦 where this page comes from