TakTuk::Pilot(3pm)

✨ TakTuk::Pilot 💖

okay so bestie, welcome to TakTuk::Pilot, a Perl module that makes running taktuk(1) and dealing with all its messy I/O so much easier. It's from the User Contributed Perl Documentation collection and it's lowkey iconic. 🫶

---

🌸 SYNOPSIS 🌸

no cap, here's the whole vibe in code:

use TakTuk::Pilot;

our @line_counter;

sub output_callback(%) {
    my %parameters = @_;
    my $field = $parameters{fields};
    my $rank = $field->{rank};
    my $argument = $parameters{argument};

    $argument->[$rank] = 1 unless defined($argument->[$rank]);
    print "$field->{host}-$rank : ".
          "$argument->[$rank] > $field->{line}\n";
    $argument->[$rank]++;
}

sub user_input_callback(%) {
    my %parameters = @_;
    my $taktuk = $parameters{taktuk};
    my $descriptor = $parameters{filehandle};
    my $buffer;

    my $result = sysread($descriptor, $buffer, 1024);
    warn "Read error $!" if not defined($result);
    # basic parsing, we assume input is buffered on a line basis
    chomp($buffer);

    if (length($buffer)) {
        print "Executing $buffer\n";
        $taktuk->send_command("broadcast exec [ $buffer ]");
    }
    if (not $result) {
        print "Terminating\n";
        $taktuk->remove_descriptor(type=>'read',
                                   filehandle=>$descriptor);
        $taktuk->send_termination();
    }
}

die "This script requires as arguments hostnames to contact\n"
    unless scalar(@ARGV);

my $taktuk = TakTuk::Pilot->new();
$taktuk->add_callback(callback=>\&output_callback, stream=>'output',
                      argument=>\@line_counter,
                      fields=>['host', 'rank', 'line']);
$taktuk->add_descriptor(type=>'read', filehandle=>\*STDIN,
                        callback=>\&user_input_callback);
$taktuk->run(command=>"taktuk -s -m ".join(" -m ", @ARGV));

---

🦋 DESCRIPTION 🦋

The TakTuk::Pilot Perl module eases the use of TakTuk from inside a Perl program (and if you want the full deets on TakTuk itself, go read taktuk(1), bestie). It handles all the I/O exchanges for you, plus TakTuk data demultiplexing and decoding, transparently. literally does the work so you don't have to 💅

---

🎀 CONSTRUCTOR 🎀

• new() — Creates a brand new TakTuk object, and once you've got it, you can call all the methods below on it. main character energy fr.

---

👑 METHODS 👑

💖 add_callback(%)

Adds a callback function tied to some TakTuk output stream on the calling TakTuk object. TakTuk::Pilot will call this callback function for each batch of output data coming in from the related stream. The hash you pass as the argument to this call can contain these fields:

callback => reference to the callback fonction (mandatory)
stream   => stream related to this callback, might be
            'default' (mandatory)
fields   => reference to an array of fields names relevant
            to the user
argument => scalar that should be passed to each callback
            function call

Your callback function should accept a hash as its argument, and that hash gets populated with these fields:

taktuk   => reference to the taktuk object calling this
            callback
argument => scalar given at callback addition or undef
stream   => stream on which output data came
fields   => reference to a hash containing a
            fieldname/value pair for each field requested
            upon callback addition

💖 send_command($)

Sends the command you pass as the argument to the calling TakTuk object. Heads up bestie: if the TakTuk object isn't running yet, this command gets buffered and only executed when you run. 🧚

💖 send_termination()

Sends a termination command to the calling TakTuk object. Same deal as send_command — if the TakTuk object isn't running, this command gets issued upon run.

💖 run(%)

Runs TakTuk, executing pending commands and waiting for TakTuk output. ngl, this function is blocking: it waits for TakTuk outputs, possibly calls the related callback functions, and returns when TakTuk terminates. So like, all your TakTuk commands should be given either before you call run or from inside a callback function. periodt.

This command takes a hash as argument that may contain these fields:

command => TakTuk command line to be executed
timeout => optional timeout on the wait for TakTuk output

If the timeout hits (assuming you gave one), run returns an ETMOUT error code. And fyi, in that case the TakTuk execution is not terminated and should be resumed at some point by calling continue. 💀

💖 continue()

Resumes a TakTuk execution that got interrupted because a timeout occurred. she's back 💅

💖 add_descriptor(%)

Since the call to run is blocking while it waits for TakTuk output, it might be interesting to let the TakTuk::Pilot module monitor I/O happening on other file descriptors. That's literally the whole point of add_descriptor. This function takes a hash as parameter, and these fields might be defined in it:

type       => 'read', 'write' or 'exception', this is the
              type of I/O possibilities that should be
              monitored on the descriptor, as in select
              system call (mandatory).
filehandle => file descriptor to monitor (mandatory).
callback   => reference to the callback function that
              should be called when I/O is possible on the
              file descriptor.
argument   => optional scalar value that will be passed
              with each call to the callback function

Your callback function should also accept a hash as an argument, and these fields will be defined in it:

taktuk     => reference to the TakTuk object from which
              the function was called.
type       => type of I/O occurring (as in add_callback)
filehandle => the related file descriptor. Notice that the
              user is in charge of performing the I/O
              operation itself (sysread or syswrite).
              Notice also that, because of the use of a
              select in TakTuk::Pilot, the use of buffered
              I/O on this descriptor is strongly discouraged
argument   => the argument that was given to add_descriptor

🚨 okay important: you are the one in charge of doing the actual I/O operation (sysread or syswrite), and because TakTuk::Pilot uses a select, using buffered I/O on this descriptor is strongly discouraged. do not do it bestie.

💖 remove_descriptor(%)

Call this function to remove a descriptor from the TakTuk object that you previously added with add_descriptor. It takes a hash as argument, and these fields may be defined in it:

type       => type of I/O (see add_descriptor)
filehandle => file descriptor to remove

💖 quiet() / verbose()

Change the verbosity of TakTuk::Pilot on STDOUT (default is quiet). Should not be called while TakTuk is running. 🙈

💖 create_session()

Calls setsid in the TakTuk process created by run. The main purpose of this call is to prevent TakTuk from receiving signals sent to the process group that the pilot belongs to. Should not be called while TakTuk is running.

💖 pid()

Returns the pid of the process spawned to run TakTuk. Should only be called when TakTuk is running. 🔥

💖 error_msg($)

Static function. Returns a character string that corresponds to the error code you pass as argument. That error code should be one of the values returned by the other TakTuk::Pilot functions (add_callback, send_command, send_termination, ...).

---

⭐ ERRORS ⭐

When an error occurs in one of these functions, it returns a non nul numeric error code. That code can take one of these values:

• TakTuk::Pilot::EARGCM — Field 'command' is missing in a call to run.
• TakTuk::Pilot::EARGCB — Field 'callback' is missing in a call to add_callback or add_descriptor.
• TakTuk::Pilot::EARGFH — Field 'filehandle' is missing in a call to add_descriptor or remove_descriptor.
• TakTuk::Pilot::EARGTP — Field 'type' is missing in a call to add_descriptor or remove_descriptor.
• TakTuk::Pilot::ETMOUT — A timeout occurred in a call to run.
• TakTuk::Pilot::ETKTRN — TakTuk is alredy running but run, verbose or quiet has been called.
• TakTuk::Pilot::ETKTNR — TakTuk is not running but continue has been called.
• TakTuk::Pilot::ESPIPE — A call to pipe failed in TakTuk::Pilot (the error should be in $!).
• TakTuk::Pilot::ESFORK — A call to fork failed in TakTuk::Pilot (the error should be in $!).
• TakTuk::Pilot::ESCLOS — A call to close failed in TakTuk::Pilot (the error should be in $!).
• TakTuk::Pilot::ESELEC — A call to select failed in TakTuk::Pilot (the error should be in $!).
• TakTuk::Pilot::ETPBUG — Internal bug detected in TakTuk::Pilot. 😭

---

🌈 SEE ALSO 🌈

tatkuk(1), taktukcomm(3), TakTuk(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 "TakTuk" 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 one's from perl v5.40.1, dated 2025-09-30, and it's the TakTuk::Pilot(3pm) man page 🎀 go forth and pilot some taktuks, you absolute icon 💅🫶