IO::Async::Routine - execute code in an independent sub-process or thread
IO::Async::Routine
use IO::Async::Routine; use IO::Async::Channel; use IO::Async::Loop; my $loop = IO::Async::Loop->new; my $nums_ch = IO::Async::Channel->new; my $ret_ch = IO::Async::Channel->new; my $routine = IO::Async::Routine->new( channels_in => [ $nums_ch ], channels_out => [ $ret_ch ], code => sub { my @nums = @{ $nums_ch->recv }; my $ret = 0; $ret += $_ for @nums; # Can only send references $ret_ch->send( \$ret ); }, on_finish => sub { say "The routine aborted early - $_[-1]"; $loop->stop; }, ); $loop->add( $routine ); $nums_ch->send( [ 10, 20, 30 ] ); $ret_ch->recv( on_recv => sub { my ( $ch, $totalref ) = @_; say "The total of 10, 20, 30 is: $$totalref"; $loop->stop; } ); $loop->run;
This IO::Async::Notifier contains a body of code and executes it in a sub-process or thread, allowing it to act independently of the main program. Once set up, all communication with the code happens by values passed into or out of the Routine via IO::Async::Channel objects.
A choice of detachment model is available, with options being a fork()ed child process, or a thread. In both cases the code contained within the Routine is free to make blocking calls without stalling the rest of the program. This makes it useful for using existing code which has no option not to block within an IO::Async-based program.
fork()
IO::Async
Code running inside a fork()-based Routine runs within its own process; it is isolated from the rest of the program in terms of memory, CPU time, and other resources. Code running in a thread-based Routine however, shares memory and other resources such as open filehandles with the main thread.
To create asynchronous wrappers of functions that return a value based only on their arguments, and do not generally maintain state within the process it may be more convenient to use an IO::Async::Function instead, which uses an IO::Async::Routine to contain the body of the function and manages the Channels itself.
For fork()-based Routines, this is invoked after the process has exited and is passed the raw exitcode status.
For thread-based Routines, this is invoked after the thread has returned from its code block and is passed the on_joined result.
on_joined
As the behaviour of these events differs per model, it may be more convenient to use on_return and on_die instead.
on_return
on_die
Invoked if the code block returns normally. Note that fork()-based Routines can only transport an integer result between 0 and 255, as this is the actual exit() value.
exit()
Invoked if the code block fails with an exception.
The following named parameters may be passed to new or configure:
new
configure
Optional. Defines how the routine will detach itself from the main process. fork uses a child process detached using an IO::Async::Process. thread uses a thread, and is only available on threaded Perls.
fork
thread
If the model is not specified, the environment variable IO_ASYNC_ROUTINE_MODEL is used to pick a default. If that isn't defined, fork is preferred if it is available, otherwise thread.
IO_ASYNC_ROUTINE_MODEL
ARRAY reference of IO::Async::Channel objects to set up for passing values in to the Routine.
IO::Async::Channel
ARRAY reference of IO::Async::Channel objects to set up for passing values out of the Routine.
CODE reference to the body of the Routine, to execute once the channels are set up.
Optional. For fork()-based Routines, gives a reference to an array to pass to the underlying Loop fork_child method. Ignored for thread-based Routines.
Loop
fork_child
Returns an ID string that uniquely identifies the Routine out of all the currently-running ones. (The ID of already-exited Routines may be reused, however.)
Returns the detachment model in use by the Routine.
Sends the specified signal to the routine code. This is either implemented by CORE::kill() or threads::kill as required. Note that in the thread case this has the usual limits of signal delivery to threads; namely, that it works at the Perl interpreter level, and cannot actually interrupt blocking system calls.
CORE::kill()
threads::kill
Paul Evans <leonerd@leonerd.org.uk>
To install IO::Async, copy and paste the appropriate command in to your terminal.
cpanm
cpanm IO::Async
CPAN shell
perl -MCPAN -e shell install IO::Async
For more information on module installation, please visit the detailed CPAN module installation guide.