TakTuk::Pilot(3)

📦 version 3.7.8, in nixos 26.05, nixpkgs unstable

🌸 NAME 🌸

TakTuk::Pilot — aka TakTuk::Pilot(3), from the User Contributed Perl Documentation, hiiii bestie 💖 — is a Perl module that ease taktuk(1) execution and related I/O management. ✨

🦋 SYNOPSIS 🦋

Here’s the whole vibe in code form, no cap:

         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 requieres 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 makes using TakTuk from inside a Perl program way easier — peep taktuk(1) for the full TakTuk lore. It transparently manages I/O exchanges plus TakTuk data demultiplexing and decoding. It’s giving “you do the Perl, I’ll handle the chaos.” 💖

🎀 CONSTRUCTOR 🎀

🌟 `new()`

Creates a brand-new TakTuk object, and then you can call all the methods below on it. Slay. ✨

✨ METHODS ✨

🫶 `add_callback(%)`

Adds a callback function tied to some TakTuk output stream on the calling TakTuk object. TakTuk::Pilot calls this callback for each batch of output data coming in from the related stream. The hash you pass as argument may 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

The callback function should accept a hash as argument. 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 passed as argument to the calling TakTuk object. Important: if the TakTuk object is not running, this command gets buffered and executed upon run. 💅

🫶 `send_termination()`

Sends a termination command to the calling TakTuk object. Same energy as send_command: if the TakTuk object is not running, this command will be issued upon run. 🎀

🫶 `run(%)`

Runs TakTuk, executing pending commands and waiting for TakTuk output. This function is blocking, bestie: it waits for TakTuk outputs, possibly calls related callback functions, and returns when TakTuk terminates. So all TakTuk commands should be given either before calling run or within a callback function. 🦋

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

⚠️ Upon occurence of the timeout (if one has been given), run will returns an ETMOUT error code. Note the in this case TakTuk execution will not be terminated and should be resumed at some point by calling continue. 😭

🫶 `continue()`

Resumes a TakTuk execution interrupted by timeout occurence. Iconic little “we were on a break” behavior. 💫

🫶 `add_descriptor(%)`

Because calling run is blocking while it waits for TakTuk output, it might be interesting to let the TakTuk::Pilot module monitor I/O occurence related to other file descriptors. That’s exactly what add_descriptor is for. This function takes a hash as parameter where these fields might be defined:

type — 'read', 'write' or 'exception'; this is the type of I/O possiblities 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

The 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 occuring (as in add_callback)
filehandle — the related file descriptor. Notice that the user is in charge of performing the I/O operation itslef (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

🫶 `remove_descriptor(%)`

Call this function to remove from the TakTuk object a descriptor previously added with add_descriptor. It takes a hash as argument where these fields may be defined:

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 when TakTuk is running. Respect the boundary, bestie. 🚫

🫶 `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 to which the pilot belong. Should not be called when TakTuk is running. 💅

🫶 `pid()`

Returns the pid of the process spawned to run TakTuk. Should only be called when TakTuk is running. Don’t ask for the pid when there’s no process, bestie 😭

🫶 `error_msg($)`

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

💀 ERRORS 💀

When an error occur in one of these functions, it returns a non nul numeric error code. This 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 occured 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. 🫶

Cute sign-off: this page is TakTuk::Pilot(3) from the User Contributed Perl Documentation, served by perl v5.42.3 and dated 1980-01-01. Bye bestie, go pilot some TakTuk 💅✨

📦 where this page comes from

nixos 26.05: taktuk 3.7.7
nixpkgs unstable: taktuk 3.7.8
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms

TakTuk::Pilot(3)

🌸 NAME 🌸

🦋 SYNOPSIS 🦋

💅 DESCRIPTION 💅

🎀 CONSTRUCTOR 🎀

🌟 new()

✨ METHODS ✨

🫶 add_callback(%)

🫶 send_command($)

🫶 send_termination()

🫶 run(%)

🫶 continue()

🫶 add_descriptor(%)

🫶 remove_descriptor(%)

🫶 quiet() / verbose()

🫶 create_session()

🫶 pid()

🫶 error_msg($)