IO::Async::Routine(3pmUser Contributed Perl DocumentatiIO::Async::Routine(3pm)
NAME
"IO::Async::Routine" - execute code in an independent sub-process or
thread
SYNOPSIS
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;
DESCRIPTION
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.
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.
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.
Models
A choice of detachment model is available. Each has various advantages
and disadvantages. Not all of them may be available on a particular
system.
The "fork" model
The code in this model runs within its own process, created by calling
"fork()" from the main process. It is isolated from the rest of the
program in terms of memory, CPU time, and other resources. Because it
is started using "fork()", the initial process state is a clone of the
main process.
This model performs well on UNIX-like operating systems which possess a
true native "fork()" system call, but is not available on "MSWin32" for
example, because the operating system does not provide full fork-like
semantics.
The "thread" model
The code in this model runs inside a separate thread within the main
process. It therefore shares memory and other resources such as open
filehandles with the main thread. As with the "fork" model, the initial
thread state is cloned from the main controlling thread.
This model is only available on perls built to support threading.
The "spawn" model
Since version 0.79.
The code in this model runs within its own freshly-created process
running another copy of the perl interpreter. Similar to the "fork"
model it therefore has its own memory, CPU time, and other resources.
However, since it is started freshly rather than by cloning the main
process, it starts up in a clean state, without any shared resources
from its parent.
Since this model creates a new fresh process rather than sharing
existing state, it cannot use the "code" argument to specify the
routine body; it must instead use only the "module" and "func"
arguments.
In the current implementation this model requires exactly one input
channel and exactly one output channel; both must be present, and there
cannot be more than one of either.
EVENTS
on_finish $exitcode
For "fork()"-based Routines, this is invoked after the process has
exited and is passed the raw exitcode status.
on_finish $type, @result
For thread-based Routines, this is invoked after the thread has
returned from its code block and is passed the "on_joined" result.
As the behaviour of these events differs per model, it may be more
convenient to use "on_return" and "on_die" instead.
on_return $result
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.
on_die $exception
Invoked if the code block fails with an exception.
PARAMETERS
The following named parameters may be passed to "new" or "configure":
model => "fork" | "thread" | "spawn"
Optional. Defines how the routine will detach itself from the main
process. See the "Models" section above for more detail.
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".
channels_in => ARRAY of IO::Async::Channel
ARRAY reference of IO::Async::Channel objects to set up for passing
values in to the Routine.
channels_out => ARRAY of IO::Async::Channel
ARRAY reference of IO::Async::Channel objects to set up for passing
values out of the Routine.
code => CODE
CODE reference to the body of the Routine, to execute once the channels
are set up.
When using the "spawn" model, this is not permitted; you must use
"module" and "func" instead.
module => STRING
func => STRING
Since version 0.79.
An alternative to the "code" argument, which names a module to load and
a function to call within it. "module" should give a perl module name
(i.e. "Some::Name", not a filename like Some/Name.pm), and "func"
should give the basename of a function within that module (i.e. without
the module name prefixed). It will be invoked as the main code body of
the object, and passed in a list of all the channels; first the input
ones then the output ones.
module::func( @channels_in, @channels_out )
setup => ARRAY
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.
METHODS
id
$id = $routine->id
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.)
model
$model = $routine->model
Returns the detachment model in use by the Routine.
kill
$routine->kill( $signal )
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.
result_future
$f = $routine->result_future
Since version 0.75.
Returns a new "IO::Async::Future" which will complete with the eventual
return value or exception when the routine finishes.
If the routine finishes with a successful result then this will be the
"done" result of the future. If the routine fails with an exception
then this will be the "fail" result.
AUTHOR
Paul Evans <leonerd@leonerd.org.uk>
perl v5.34.0 2022-08-19 IO::Async::Routine(3pm)
Generated by dwww version 1.15 on Mon Jul 1 01:43:12 CEST 2024.