Mojo::...rocess(3pm)

🦋 NAME 🦋

Mojo::IOLoop::ReadWriteProcess — okay bestie, this is the one that executes external programs or internal code blocks as a separate process. Yes, forking. Yes, it's giving main character energy. Sit down, we're doing this 💅

---

✨ SYNOPSIS ✨

use Mojo::IOLoop::ReadWriteProcess;

# Code fork
my $process = Mojo::IOLoop::ReadWriteProcess->new(sub { print "Hello\n" });
$process->start();
print "Running\n" if $process->is_running();
$process->getline(); # Will return "Hello\n"
$process->pid(); # Process id
$process->stop();
$process->wait_stop(); # if you intend to wait its lifespan

# Methods can be chained, thus this is valid:
use Mojo::IOLoop::ReadWriteProcess qw(process);
my $output = process( sub { print "Hello\n" } )->start()->wait_stop->getline;

# Handles seamelessy also external processes:
my $process = process(execute=> '/path/to/bin' )->args([qw(foo bar baz)]);
$process->start();
my $line_output = $process->getline();
my $pid = $process->pid();
$process->stop();
my @errors = $process->error;

# To help when debugging Mojo::Collections
use Mojo::Util qw(dumper);
my $errors = dumper $process->error->to_array;

# Get process return value
$process = process( sub { return "256"; } )->start()->wait_stop;
# We need to stop it to retrieve the exit status
my $return = $process->return_status;

# We can access directly to handlers from the object:
my $stdout = $process->read_stream;
my $stdin = $process->write_stream;
my $stderr = $process->error_stream;

# So this works:
print $stdin "foo bar\n";
my @lines = <$stdout>;

# There is also an alternative channel of communication (just for forked processes):
my $channel_in = $process->channel_in; # write to the child process
my $channel_out = $process->channel_out; # read from the child process
$process->channel_write("PING"); # convenience function

The way that chaining just works? Obsessed. 🫶

---

💖 DESCRIPTION 💖

Mojo::IOLoop::ReadWriteProcess is yet another process manager. That's it. That's the pitch. Short, iconic, no notes. 👑

---

🌈 EVENTS 🌈

Mojo::IOLoop::ReadWriteProcess inherits all events from Mojo::EventEmitter and can emit the following new ones. New ones only, bestie — the inherited ones are somebody else's business.

🎀 start

$process->on(start => sub {
  my ($process) = @_;
  $process->is_running();
});

Emitted when the process starts. Like, it's alive, she's here, everybody say hi 🦋

🎀 stop

$process->on(stop => sub {
  my ($process) = @_;
  $process->restart();
});

Emitted when the process stops. Rest in peace queen 😭

🎀 process_error

$process->on(process_error => sub {
  my ($e) = @_;
  my @errors = @{$e};
});

Emitted when the process produce errors. Not the vibe, but we listen.

🎀 process_stuck

$process->on(process_stuck => sub {
  my ($self) = @_;
  ...
});

Emitted when blocking_stop is set and all attempts for killing the process in max_kill_attempts have been exhausted. The event is emitted before attempting to kill it with SIGKILL and becoming blocking. It's giving last resort. 💀

🎀 SIG_CHLD

$process->on(SIG_CHLD => sub {
  my ($self) = @_;
  ...
});

Emitted when we receive SIG_CHLD.

🎀 SIG_TERM

$process->on(SIG_TERM => sub {
  my ($self) = @_;
  ...
});

Emitted when the child forked process receives SIG_TERM, before exiting.

🎀 collected

$process->on(collected => sub {
  my ($self) = @_;
  ...
});

Emitted right after status collection. Freshly collected. Still warm. 🍓

🎀 collect_status

$process->on(collect_status => sub {
  my ($self) = @_;
  ...
});

Emitted when on child process waitpid. It is used internally to get the child process status.

⚠️ Note: events attached to it are wiped when process has been stopped. Gone. Poof. 💀

---

👑 ATTRIBUTES 👑

Mojo::IOLoop::ReadWriteProcess inherits all attributes from Mojo::EventEmitter and implements the following new ones.

💜 execute

use Mojo::IOLoop::ReadWriteProcess;
my $process = Mojo::IOLoop::ReadWriteProcess->new(execute => "/usr/bin/perl");
$process->start();
$process->on( stop => sub { print "Process: ".(+shift()->pid)." finished"; } );
$process->stop();

execute should contain the external program that you wish to run. Like, the actual binary. The whole thing. Slay.

💜 code

use Mojo::IOLoop::ReadWriteProcess;
my $process = Mojo::IOLoop::ReadWriteProcess->new(code => sub { print "Hello" } );
$process->start();
$process->on( stop => sub { print "Process: ".(+shift()->pid)." finished"; } );
$process->stop();

It represent the code you want to run in background.

Good news: you do not need to specify code, it is implied if no arguments is given. Look how chill:

my $process = Mojo::IOLoop::ReadWriteProcess->new(sub { print "Hello" });
$process->start();
$process->on( stop => sub { print "Process: ".(+shift()->pid)." finished"; } );
$process->stop();

💜 args

use Mojo::IOLoop::ReadWriteProcess;
my $process = Mojo::IOLoop::ReadWriteProcess->new(code => sub { print "Hello ".$_[1] }, args => "User" );
$process->start();
$process->on( stop => sub { print "Process: ".(+shift()->pid)." finished"; } );
$process->stop();

# The process will print "Hello User"

Arguments pass to the external binary or the code block. Got lots of them? Use arrayref to pass many. ✨

💜 blocking_stop

use Mojo::IOLoop::ReadWriteProcess;
my $process = Mojo::IOLoop::ReadWriteProcess->new(code => sub { print "Hello" }, blocking_stop => 1 );
$process->start();
$process->on( stop => sub { print "Process: ".(+shift()->pid)." finished"; } );
$process->stop(); # Will wait indefinitely until the process is stopped

Set it to 1 if you want to do blocking stop of the process. Emphasis on indefinitely — she will wait, bestie. She has nothing else going on. 😭

💜 channels

use Mojo::IOLoop::ReadWriteProcess;
my $process = Mojo::IOLoop::ReadWriteProcess->new(code => sub { print "Hello" }, channels => 0 );
$process->start();
$process->on( stop => sub { print "Process: ".(+shift()->pid)." finished"; } );
$process->stop(); # Will wait indefinitely until the process is stopped

Set it to 0 if you want to disable internal channels. Turning off the group chat fr fr 🙈

💜 session

use Mojo::IOLoop::ReadWriteProcess;
my $process = Mojo::IOLoop::ReadWriteProcess->new(sub { print "Hello" });
my $session = $process->session;
$session->enable_subreaper;

Returns the current Mojo::IOLoop::ReadWriteProcess::Session singleton. The one and only. Periodt.

💜 subreaper

use Mojo::IOLoop::ReadWriteProcess;
my $process = Mojo::IOLoop::ReadWriteProcess->new(code => sub { print "Hello ".$_[1] }, args => "User" );
$process->subreaper(1)->start();
$process->on( stop => sub { shift()->disable_subreaper } );
$process->stop();

# The process will print "Hello User"

Mark the current process (not the child) as subreaper on start. Heads up: it's on invoker behalf to disable subreaper when process stops, because it marks the current process and not the child. So that's your job, not hers. 🫶

💜 ioloop

my $loop    = $process->ioloop;
$subprocess = $process->ioloop(Mojo::IOLoop->new);

Event loop object to control, and it defaults to the global Mojo::IOLoop singleton. No setup required, she already knows the way. 🌸

💜 max_kill_attempts

use Mojo::IOLoop::ReadWriteProcess;
my $process = Mojo::IOLoop::ReadWriteProcess->new(code => sub { print "Hello" }, max_kill_attempts => 50 );
$process->start();
$process->on( stop => sub { print "Process: ".(+shift()->pid)." finished"; } );
$process->stop(); # It will attempt to send SIGTERM 50 times.

Defaults to 5, and it's the number of attempts before bailing out.

It can be used with blocking_stop, so if the number of attempts are exhausted, a SIGKILL and waitpid will be tried at the end. Not a drill. 💀

💜 kill_whole_group

use Mojo::IOLoop::ReadWriteProcess;
my $process = Mojo::IOLoop::ReadWriteProcess->new(code => sub { setpgrp(0, 0); exec(...); }, kill_whole_group => 1 );
$process->start();
$process->send_signal(...); # Will skip the usual check whether $process->pid is running
$process->stop();           # Kills the entire process group and waits for all processes in the group to finish

Defaults to 0, and it's whether to send signals (e.g. to stop) to the entire process group.

This is useful when the sub process creates further sub processes and creates a new process group as shown in the example. In that case it might be useful to take care of the entire process group when stopping and wait for every process in the group to finish. It's giving family plan. 👑

💜 collect_status

Defaults to 1. If enabled, it will automatically collect the status of the children process. Disable it in case you want to manage your process child directly, and do not want to rely on automatic collect status.

Heads up bestie: if you won't overwrite your SIGCHLD handler, the SIG_CHLD event will be still emitted. She's persistent like that. 💅

💜 serialize

Defaults to 0. If enabled, data returned from forked process will be serialized with Storable. Fancy ✨

💜 kill_sleeptime

Defaults to 1. It's the seconds to wait before attempting SIGKILL when blocking_stop is set to 1. A lil nap before the violence. 😴

💜 separate_err

Defaults to 1. It will create a separate channel to intercept process STDERR, otherwise it will be redirected to STDOUT. Keep your streams in separate group chats, bestie.

💜 verbose

Defaults to 1. It indicates message verbosity. She talks. A lot. Iconic.

💜 set_pipes

Defaults to 1. If enabled, additional pipes for process communication are automatically set up. Plumbing, but make it cute 🎀

💜 internal_pipes

Defaults to 1. If enabled, additional pipes for retreiving process return and errors are set up.

⚠️ Note: if you disable that, the only information provided by the process will be the exit_status. That's it. That's all you get. 💀

💜 autoflush

Defaults to 1. If enabled, autoflush of handlers is enabled automatically. No buffering drama. Slay.

💜 error

Returns a Mojo::Collection of errors.

⚠️ Note: errors that can be captured only at the end of the process. So don't come looking for them early, bestie, they're not ready yet. 🍓

✨ METHODS ✨

Okay bestie, so Mojo::IOLoop::ReadWriteProcess inherits all the methods from Mojo::EventEmitter and then adds these new ones. Let's get into it, no cap. 💅

---

start() 🌸

use Mojo::IOLoop::ReadWriteProcess qw(process);
my $p = process(sub {
                      print STDERR "Boo\n"
                  } )->start;

Starts the process. That's it, that's the vibe. 🚀

---

stop() 🛑

use Mojo::IOLoop::ReadWriteProcess qw(process);
my $p = process( execute => "/path/to/bin" )->start->stop;

Stop the process. Unless you use wait_stop(), it will attempt to kill the process without waiting for the process to finish. By default it sends SIGTERM to the child. You can change that by defining the internal attribute _default_kill_signal. Note: if you want to be sure that the process gets killed, you can enable the blocking_stop attribute, which will attempt to send SIGKILL after max_kill_attempts is reached. 💀

---

restart() 🔄

use Mojo::IOLoop::ReadWriteProcess qw(process);
my $p = process( execute => "/path/to/bin" )->restart;

It restarts the process if stopped, or if already running, it stops it first. Slay. ✨

---

is_running() 🏃‍♀️

use Mojo::IOLoop::ReadWriteProcess qw(process);
my $p = process( execute => "/path/to/bin" )->start;
$p->is_running;

Boolean, it inspects if the process is currently running or not. 👑

---

exit_status() 🚪

use Mojo::IOLoop::ReadWriteProcess qw(process);
my $p = process( execute => "/path/to/bin" )->start;

$p->wait_stop->exit_status;

Inspect the process exit status, it does the shifting magic, to access the real value call _status(). 🤯

---

return_status() 🔙

use Mojo::IOLoop::ReadWriteProcess qw(process);
my $p = process( sub { return 42 } )->start;

my $s = $p->wait_stop->return_status; # 42

Inspect the codeblock return. It's giving "what did the child actually return?" energy. 🎁

---

enable_subreaper() 👑

use Mojo::IOLoop::ReadWriteProcess qw(process);
my $p = process()->enable_subreaper;

Mark the current process (not the child) as subreaper. This is used typically if you want to mark further children as subreapers inside other forks.

my $master_p = process(
  sub {
    my $p = shift;
    $p->enable_subreaper;

    process(sub { sleep 4; exit 1 })->start();
    process(
      sub {
        sleep 4;
        process(sub { sleep 1; })->start();
      })->start();
    process(sub { sleep 4; exit 0 })->start();
    process(sub { sleep 4; die })->start();
    my $manager
      = process(sub { sleep 2 })->subreaper(1)->start();
    sleep 1 for (0 .. 10);
    $manager->stop;
    return $manager->session->all->size;
  });

$master_p->subreaper(1);

$master_p->on(collected => sub { $status++ });

# On start we setup the current process as subreaper
# So it's up on us to disable it after process is done.
$master_p->on(stop => sub { shift()->disable_subreaper });
$master_p->start();

---

disable_subreaper() 🚫

use Mojo::IOLoop::ReadWriteProcess qw(process);
my $p = process()->disable_subreaper;

Unset the current process (not the child) as subreaper. Bye bye subreaper energy. 👋

---

prctl() 🧠

use Mojo::IOLoop::ReadWriteProcess qw(process);
my $p = process();
$p->prctl($option, $arg2, $arg3, $arg4, $arg5);

Internal function to execute and wrap the prctl syscall, accepts the same arguments as prctl. Lowkey syscall magic. 🔮

---

diag() 📢

use Mojo::IOLoop::ReadWriteProcess qw(process);
my $p = process(sub { print "Hello\n" });
$p->on( stop => sub { shift->diag("Done!") } );
$p->start->wait_stop;

Internal function to print information to STDERR if verbose attribute is set or either DEBUG mode enabled. You can use it if you wish to display information on the process status. It's like a little gossip sesh for your process. ☕

---

to_ioloop() 🌊

use Mojo::IOLoop::ReadWriteProcess qw(process);

my $p = process(sub {  print "Hello from first process\n"; sleep 1 });

$p->start(); # Start and sets the handlers
my $stream = $p->to_ioloop; # Get the stream and demand to IOLoop
my $output;

# Hook on Mojo::IOLoop::Stream events
$stream->on(read => sub { $output .= pop;  $p->is_running ...  });

Mojo::IOLoop->singleton->start() unless Mojo::IOLoop->singleton->is_running;

Returns a Mojo::IOLoop::Stream object and demand the wait operation to Mojo::IOLoop. It needs set_pipes enabled. Default IOLoop can be overridden in ioloop(). Big main character energy for your event loop. 💫

---

wait() ⏳

use Mojo::IOLoop::ReadWriteProcess qw(process);
my $p = process(sub { print "Hello\n" })->wait;
# ... here now you can mangle $p handlers and such

Waits until the process finishes, but does not perform cleanup operations (until stop is called). Just chilling until it's done. 🛋️

---

wait_stop() 🛑

use Mojo::IOLoop::ReadWriteProcess qw(process);
my $p = process(sub { print "Hello\n" })->start->wait_stop;
# $p is not running anymore, and all possible events have been granted to be emitted.

Waits until the process finishes, and performs cleanup operations. The full send-off. 🎉

---

errored() ❌

use Mojo::IOLoop::ReadWriteProcess qw(process);
my $p = process(sub { die "Nooo" })->start->wait_stop;
$p->errored; # will return "1"

Returns a boolean indicating if the process had errors or not. So if your process is giving messy, this will tell you. 😭

---

write_pidfile() 📝

use Mojo::IOLoop::ReadWriteProcess qw(process);
my $p = process(sub { die "Nooo" } );
$p->pidfile("foobar");
$p->start();
$p->write_pidfile();

Forces writing PID of process to specified pidfile in the attributes of the object. Useful only if the process have been already started, otherwise if a pidfile it's supplied as attribute, it will be done automatically. PID flex. 💪

---

write_stdin() ✍️

use Mojo::IOLoop::ReadWriteProcess qw(process);
my $p = process(sub { my $a = <STDIN>; print STDERR "Hello my name is $a\n"; } )->start;
$p->write_stdin("Larry");
$p->read_stderr; # process STDERR will contain: "Hello my name is Larry\n"

Write data to process STDIN. Sending messages directly to your child's inbox. 📨

---

write_channel() 📡

use Mojo::IOLoop::ReadWriteProcess qw(process);
my $p = process(sub {
                      my $self = shift;
                      my $parent_output = $self->channel_out;
                      my $parent_input  = $self->channel_in;

                      while(defined(my $line = <$parent_input>)) {
                        print $parent_output "PONG\n" if $line =~ /PING/i;
                      }
                  } )->start;
$p->write_channel("PING");
my $out = $p->read_channel;
# $out is PONG
my $child_output = $p->channel_out;
while(defined(my $line = <$child_output>)) {
    print "Process is replying back with $line!\n";
    $p->write_channel("PING");
}

Write data to process channel. Note, it's not STDIN, neither STDOUT, it's a complete separate channel dedicated to parent-child communication. In the parent process, you can access to the same pipes (but from the opposite direction):

my $child_output = $self->channel_out;
my $child_input  = $self->channel_in;

It's giving secret tunnel vibes. 🤫

---

read_stdout() 📖

use Mojo::IOLoop::ReadWriteProcess qw(process);
my $p = process(sub {
                      print "Boo\n"
                  } )->start;
$p->read_stdout;

Gets a single line from process STDOUT. One line at a time, bestie. 🍓

---

read_channel() 📻

use Mojo::IOLoop::ReadWriteProcess qw(process);
my $p = process(sub {
                      my $self = shift;
                      my $parent_output = $self->channel_out;
                      my $parent_input  = $self->channel_in;

                      print $parent_output "PONG\n";
                  } )->start;
$p->read_channel;

Gets a single line from process channel. Just one line, no more. 🎀

---

read_stderr() 📢

use Mojo::IOLoop::ReadWriteProcess qw(process);
my $p = process(sub {
                      print STDERR "Boo\n"
                  } )->start;
$p->read_stderr;

Gets a single line from process STDERR. Error gossip, but make it one line. 😈

---

read_all_stdout() 📚

use Mojo::IOLoop::ReadWriteProcess qw(process);
my $p = process(sub {
                      print "Boo\n"
                  } )->start;
$p->read_all_stdout;

Gets all the STDOUT output of the process. The whole shebang. 🌈

---

read_all_channel() 📬

use Mojo::IOLoop::ReadWriteProcess qw(process);
my $p = process(sub {
                      shift->channel_out->write("Ping")
                  } )->start;
$p->read_all_channel;

Gets all the channel output of the process. Every last drop. 💧

---

read_all_stderr() 📯

use Mojo::IOLoop::ReadWriteProcess qw(process);
my $p = process(sub {
                      print STDERR "Boo\n"
                  } )->start;
$p->read_all_stderr;

Gets all the STDERR output of the process. All the tea. ☕

---

send_signal() 📶

use Mojo::IOLoop::ReadWriteProcess qw(process);
use POSIX;
my $p = process( execute => "/path/to/bin" )->start;

$p->send_signal(POSIX::SIGKILL);

Send a signal to the process. Like sliding into its DMs but with signals. ⚡

---

✨ EXPORTS ✨

parallel() 🧵

use Mojo::IOLoop::ReadWriteProcess qw(parallel);
my $pool = parallel sub { print "Hello\n" } => 5;
$pool->start();
$pool->on( stop => sub { print "Process: ".(+shift()->pid)." finished"; } );
$pool->stop();

Returns a Mojo::IOLoop::ReadWriteProcess::Pool object that represent a group of processes.

It accepts the same arguments as Mojo::IOLoop::ReadWriteProcess, and the last one represent the number of processes to generate. Squad goals. 👯‍♀️

---

batch() 📦

use Mojo::IOLoop::ReadWriteProcess qw(batch);
my $pool = batch;
$pool->add(sub { print "Hello\n" });
$pool->on(stop => sub { shift->_diag("Done!") })->start->wait_stop;

Returns a Mojo::IOLoop::ReadWriteProcess::Pool object generated from supplied arguments. It accepts as input the same parameter of Mojo::IOLoop::ReadWriteProcess::Pool constructor ( see parallel() ). Batch them all. 🍪

---

process() 🏭

use Mojo::IOLoop::ReadWriteProcess qw(process);
my $p = process sub { print "Hello\n" };
$p->start()->wait_stop;

or even:

process(sub { print "Hello\n" })->start->wait_stop;

Returns a Mojo::IOLoop::ReadWriteProcess object that represent a process.

It accepts the same arguments as Mojo::IOLoop::ReadWriteProcess. The OG. 👑

---

queue() 🎟️

use Mojo::IOLoop::ReadWriteProcess qw(queue);
my $q = queue;
$q->add(sub { return 42 } );
$q->consume;

Returns a Mojo::IOLoop::ReadWriteProcess::Queue object that represent a queue. Line up, bestie. 🚶‍♀️

---

✨ DEBUGGING ✨

You can set the MOJO_EVENTEMITTER_DEBUG environment variable to get some advanced diagnostics information printed to STDERR.

MOJO_EVENTEMITTER_DEBUG=1

Also, you can set MOJO_PROCESS_DEBUG environment variable to get diagnostics about the process execution.

MOJO_PROCESS_DEBUG=1

Turn on the debug tea and watch the magic. 🐛🔍

📜 LICENSE (the legal tea) 📜

Copyright (C) Ettore Di Giacinto.

Okay bestie, here's the part where the lawyers make us say the thing, but it's actually good news:

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. 💖

That's it. That's the whole license. Go forth and remix, babes. 🎀

---

👑 AUTHOR 👑

Ettore Di Giacinto <edigiacinto@suse.com>

The icon who wrote this whole thing. Give them their flowers. 🌸💐

---

fr fr, that's a wrap on the whole page — every option, every event, every tiny little default, all of it, no cap. 💅

This page was served up from perl v5.42.0 on 2025-07-25, and it's Mojo::...rocess(3pm) — so if you're reading this, you officially know your way around a process. Periodt. 🦋✨