Future...System(3pm)

🌸 NAME 🌸

okay so this is Future::IO::System, aka the Future...System(3pm) page — user-contributed Perl documentation, bestie. 💅 It’s literally the "system()"-like methods package for Future::IO. No cap.

---

✨ SYNOPSIS ✨

use Future::IO;
use Future::IO::System;

my $f = Future::IO::System->system( "cmd", "args go", "here" );
# $f will become done when the command completes

my $f = Future::IO::System->system_out( "cmd", "-v" );
my ( $status, $out ) = $f->get;

# $status will contain the exit code and $out will contain what it wrote
# to STDOUT

---

🦋 DESCRIPTION 🦋

This package contains a selection of methods that behave like the core system() and related functions, running asynchronously via Future::IO. 🫶

In particular, the "system" behaves somewhat like CORE::system() and "system_out" behaves somewhat like qx(). iconic behavior, honestly.

🧚 Portability

In order for this module to work at all, the underlying Future::IO implementation must support the waitpid in Future::IO method. The default minimal implementation included with the module does not, but most of the additional implementations from CPAN will. 🫡

In addition, the operation of this module uses techniques that only really work on full POSIX systems (such as Linux, Mac OS X, the various BSDs, etc). It is unlikely to work in places like MSWin32. 💀 vibe check: not MSWin32-friendly.

---

🛠️ METHODS 🛠️

🏃 run

( $exitcode, ... ) = await Future::IO::System->run(
   argv => [ $path, @args ],
   ...
);

Since version 0.12. ✨

Runs the given $path with the given @args as a sub-process, optionally with some additional filehandles set up as determined by the other arguments. The returned Future will yield the waitpid() exit code from the process when it terminates, and optionally the bytes read from the other filehandles that were set up. 👑

Takes the following named arguments:

• argv => ARRAY — an array reference containing the path and arguments to pass to exec() in the child process. 🧚
• in => STRING — if defined, create a pipe and assign the reading end to the child process's STDIN filehandle. The given string will then be written to the pipe, after which the pipe will be closed. 🎀
• want_out => BOOL — if true, create a pipe and assign the writing end to the child process's STDOUT filehandle. The returned future will additionally contain all the bytes read from it until EOF. 🌈
• want_err => BOOL — if true, create a pipe and assign the writing end to the child process's STDERR filehandle. The returned future will additionally contain all the bytes read from it until EOF. 🍓

The remaining methods in this class are simplified wrappers of this one. Slay. 💅

🧨 system

$exitcode = await Future::IO::System->system( $path, @args );

Since version 0.12. ⭐

Runs the given $path with the given @args as a sub-process with no extra filehandles. Simple, clean, main character energy. 👑

💖 system_out

( $exitcode, $out ) = await Future::IO::System->system_out( $path, @args );

Since version 0.12. 🦋

Runs the given $path with the given @args as a sub-process with a new pipe as its STDOUT filehandle. The returned Future will additionally yield the bytes read from the STDOUT pipe. Obsessed. ✨

---

📝 TODO 📝

• Add some OS portability guard warnings when loading the module on platforms not known to support it. 🫶
• Consider what other features of modules like IPC::Run or IO::Async::Process to support here. Try not to go overboard. 😭

---

👑 AUTHOR 👑

Paul Evans <leonerd@leonerd.org.uk> — periodt. 💜

---

mwah 💋 that’s the whole page, bestie. brought to you by perl v5.40.0, dated 2024-09-21, and yes it’s the Future...System(3pm) manual page. slay and goodbye. 🎀