NAME

       Mojo::IOLoop::Subprocess - Subprocesses

SYNOPSIS

         use Mojo::IOLoop::Subprocess;

         # Operation that would block the event loop for 5 seconds
         my $subprocess = Mojo::IOLoop::Subprocess->new;
         $subprocess->run(
           sub {
             my $subprocess = shift;
             sleep 5;
             return '♥', 'Mojolicious';
           },
           sub {
             my ($subprocess, $err, @results) = @_;
             say "Subprocess error: $err" and return if $err;
             say "I $results[0] $results[1]!";
           }
         );

         # Start event loop if necessary
         $subprocess->ioloop->start unless $subprocess->ioloop->is_running;

DESCRIPTION

       Mojo::IOLoop::Subprocess allows Mojo::IOLoop to perform computationally expensive
       operations in subprocesses, without blocking the event loop.

EVENTS

       Mojo::IOLoop::Subprocess inherits all events from Mojo::EventEmitter and can emit the
       following new ones.

   cleanup
         $subprocess->on(cleanup => sub {
           my $subprocess = shift;
           ...
         });

       Emitted in the subprocess right before the process will exit. Note that this event is
       EXPERIMENTAL and might change without warning!

         $subprocess->on(cleanup => sub {
           my $subprocess = shift;
           say "Process $$ is about to exit";
         });

   progress
         $subprocess->on(progress => sub {
           my ($subprocess, @data) = @_;
           ...
         });

       Emitted in the parent process when the subprocess calls the progress method.

   spawn
         $subprocess->on(spawn => sub {
           my $subprocess = shift;
           ...
         });

       Emitted in the parent process when the subprocess has been spawned.

         $subprocess->on(spawn => sub {
           my $subprocess = shift;
           my $pid = $subprocess->pid;
           say "Performing work in process $pid";
         });

ATTRIBUTES

       Mojo::IOLoop::Subprocess implements the following attributes.

   deserialize
         my $cb      = $subprocess->deserialize;
         $subprocess = $subprocess->deserialize(sub {...});

       A callback used to deserialize subprocess return values, defaults to using Storable.

         $subprocess->deserialize(sub {
           my $bytes = shift;
           return [];
         });

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

       Event loop object to control, defaults to the global Mojo::IOLoop singleton.  Note that
       this attribute is weakened.

   serialize
         my $cb      = $subprocess->serialize;
         $subprocess = $subprocess->serialize(sub {...});

       A callback used to serialize subprocess return values, defaults to using Storable.

         $subprocess->serialize(sub {
           my $array = shift;
           return '';
         });

METHODS

       Mojo::IOLoop::Subprocess inherits all methods from Mojo::EventEmitter and implements the
       following new ones.

   pid
         my $pid = $subprocess->pid;

       Process id of the spawned subprocess if available.

   progress
         $subprocess->progress(@data);

       Send data serialized with Storable to the parent process at any time during the
       subprocess's execution. Must be called by the subprocess and emits the "progress" event in
       the parent process with the data.

         # Send progress information to the parent process
         $subprocess->run(
           sub {
             my $subprocess = shift;
             $subprocess->progress('0%');
             sleep 5;
             $subprocess->progress('50%');
             sleep 5;
             return 'Hello Mojo!';
           },
           sub {
             my ($subprocess, $err, @results) = @_;
             say 'Progress is 100%';
             say $results[0];
           }
         );
         $subprocess->on(progress => sub {
           my ($subprocess, @data) = @_;
           say "Progress is $data[0]";
         });

   run
         $subprocess = $subprocess->run(sub {...}, sub {...});

       Execute the first callback in a child process and wait for it to return one or more
       values, without blocking "ioloop" in the parent process. Then execute the second callback
       in the parent process with the results. The return values of the first callback and
       exceptions thrown by it, will be serialized with Storable, so they can be shared between
       processes.

SEE ALSO

       Mojolicious, Mojolicious::Guides, <https://mojolicious.org>.