=head1 NAME
Mojo::IOLoop::ForkCall - (DEPRECATED) run blocking functions asynchronously by forking
=head1 SYNOPSIS
use Mojo::IOLoop::ForkCall my $fc = Mojo::IOLoop::ForkCall->new; $fc->run( \&expensivefunction, ['arg', 'list'], sub { my ($fc, $err, @return) = @; ... } ); $fc->ioloop->start unless $fc->ioloop->is_running;
=head1 DESCRIPTION
DEPRECATED!
This module is deprecated in favor of the L
Asynchronous programming can be benefitial for performance, however not all functions are written for nonblocking interaction and external processes almost never are. Still, all is not lost.
By forking the blocking call into a new process, the main thread may continue to run non-blocking, while the blocking call evaluates. Mojo::IOLoop::ForkCall manages the forking and will emit an event (or execute a callback) when the forked process completes. Return values are serialized and sent from the child to the parent via an appropriate pipe for your platform.
This module is heavily inspired by L
For simple cases in a L
=head1 WARNINGS
Some platforms do not fork well, some platforms don't pipe well. This module and the libraries it relies on do their best to smooth over these differences. Still some attention should be paid to platform specific usage, especially on Windows. Efficiency/performance on Windows is not likely to be very good.
N.B. There was previously a warning about using event-based programming in the child. As of version 0.10, this warning is lifted as the child process will reset the singleton loop, as well as the loop refered to in the ForkCall instance. Still, use with caution, and no running with scissors!
=head1 EVENTS
This module inherits all events from L
=head2 error
$fc->on( error => sub { my ($fc, $err) = @_; } );
Emitted in the parent when the parent process encounters an error. Fatal if not handled.
=head2 finish
$fc->on( finish => sub { my ($fc, $err, @returnvalues) = @; ... });
Emitted in the parent process once the child process completes and sends its results.
The callback is passed the ForkCall instance, any error, then all deserialized results from the child.
Note that this event is called for each C
=head2 spawn
$fc->on( spawn => sub { my ($fc, $childpid) = @; ... } );
Emitted in the parent process when a child process is spawned. The callback is passed the ForkCall instance and the child pid.
=head1 ATTRIBUTES
This module inherits all attributes from L
=head2 ioloop
The L
=head2 serializer
A code reference to serialize the results of the child process to send to the parent. Note that as this code reference is called in the child, some care should be taken when setting it to something other than the defaults. Defaults to C<\&Storable::freeze>.
The code reference will be passed a single array reference. The first argument will be any error or undef if no error occured. If there was no error, the remaining elements of the array will be the values returned by the job (evaluated in list context).
=head2 deserializer
A code reference used to deserialize the results of the child process.
Defaults to C<\&Storable::thaw>.
This should be the logical inverse of the C
=head2 weaken
If true, the reference to the ForkCall object will be weakened in the internals to prevent a possible memory leak should the child process never close. In this case, if you do not maintain a reference to the ForkCall object, the first argument to the callback will be undef. Additionally, the finish event may not be emitted. Defaults to false. Do not use this unless you know what you are doing and why!
=head1 METHODS
This module inherits all METHODS from L
=head2 run
my $fc = Mojo::IOLoop::ForkCall->new; $fc = $fc->run( sub { my @args = @_; ... return @res }, \@args, sub { my ($fc, $err, @returnvalues) = @; ... } );
Takes a code reference (required) which is the job to be run on the child.
If the next argument is an array reference, these will be passed to the child job.
If the last argument is a code reference, it will be called immediately before the finish event is emitted, its arguments are the same as the C
=head1 EXPORTED FUNCTIONS
Upon request this module exports the following functions.
=head2 fork_call
forkcall { my @args = @; child code; return @res } @args, sub { my @res = @_; parent callback }
This function is a drop-in replacement for L
The function takes a block to be performed in the child, a list of arguments to pass to the block, and a callback to be run on completion. Note that the callback is required and that the arguments are given as a list, not an arrayreference (unlike the OO style). The callback will receive the deserialized return values from the child block as C<@_>. Any error will be available in C<$@>.
The underlying ForkCall object will use its default attributes. The return value is the created ForkCall instance.
WARNING: In Perl versions before 5.14, if the parent callback dies, the exception is silently ignored. This is a limitation in those Perl interpreters and was fixed in L<5.14|perl5140delta/"Exception Handling">. Yet another reason to use the object-oriented interface, which does not suffer from this limitation!
=head1 SEE ALSO
=over
=item L
=item L
=item L
=back
=head1 FUTURE WORK
=over
=item *
Investigate hooking into the L<Mojo::IOLoop::Stream/timeout> event to kill runaway children.
=back
=head1 KNOWN ISSUES
=over
=item *
Although in concept this module works on windows, in practical cases running real-world apps with this module on windows might spectularly crash. This is unfortunately not solvable from the Perl level and must be addressed in the C level interpreter code. The good news is that recent interpreters seem not to be having this issue. See Lhttps://github.com/jberger/Mojo-IOLoop-ForkCall/issues/5.
=back
=head1 SOURCE REPOSITORY
Lhttp://github.com/jberger/Mojo-IOLoop-ForkCall
=head1 AUTHOR
Joel Berger, Elt>joel.a.berger@gmail.comE<gt
=head1 CONTRIBUTORS
=over
=item Dan Book (Grinnz)
=back
=head1 COPYRIGHT AND LICENSE
Copyright (C) 2013-2015 by Joel Berger
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.