use IO::Async::Function;
use IO::Async::Loop;
my $loop = IO::Async::Loop->new;
my $function = IO::Async::Function->new(
code => sub {
my ( $number ) = @_;
return is_prime( $number );
},
);
$loop->add( $function );
$function->call(
args => [ 123454321 ],
)->on_done( sub {
my $isprime = shift;
print "123454321 " . ( $isprime ? "is" : "is not" ) . " a prime number\n";
})->on_fail( sub {
print STDERR "Cannot determine if it's prime - $_[0]\n";
})->get;
The object represents the function code itself, rather than one specific invocation of it. It can be called multiple times, by the "call" method. Multiple outstanding invocations can be called; they will be dispatched in the order they were queued. If only one worker process is used then results will be returned in the order they were called. If multiple are used, then each request will be sent in the order called, but timing differences between each worker may mean results are returned in a different order.
Since the code block will be called multiple times within the same child process, it must take care not to modify any of its state that might affect subsequent calls. Since it executes in a child process, it cannot make any modifications to the state of the parent program. Therefore, all the data required to perform its task must be represented in the call arguments, and all of the result must be represented in the return values.
The Function object is implemented using an IO::Async::Routine with two IO::Async::Channel objects to pass calls into and results out from it.
The IO::Async framework generally provides mechanisms for multiplexing IO tasks between different handles, so there aren't many occasions when such an asynchronous function is necessary. Two cases where this does become useful are:
This object is ideal for representing ``pure'' functions; that is, blocks of code which have no stateful effect on the process, and whose result depends only on the arguments passed in. For a more general co-routine ability, see also IO::Async::Routine.
@result = $code->( @args )
$init_code->()
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, without extra arguments, as the main code body of the object.
The task of loading this module and resolving the resulting function from it is only performed on the remote worker side, so the controlling process will not need to actually load the module.
If this value is an array reference, its first element must be a string giving the name of the function; the remaining values are passed to that function as arguments.
$function->start
$function->stop
Stop the worker processes
$f = $function->stop
Since version 0.75.
If called in non-void context, returns a IO::Async::Future instance that will complete once every worker process has stopped and exited. This may be useful for waiting until all of the processes are waited on, or other edge-cases, but is not otherwise particularly useful.
$function->restart
Gracefully stop and restart all the worker processes.
@result = $function->call( %params )->get
Schedules an invocation of the contained function to be executed on one of the worker processes. If a non-busy worker is available now, it will be called immediately. If not, it will be queued and sent to the next free worker that becomes available.
The request will already have been serialised by the marshaller, so it will be safe to modify any referenced data structures in the arguments after this call returns.
The %params hash takes the following keys:
Higher values cause the call to be considered more important, and will be placed earlier in the queue than calls with a smaller value. Calls of equal priority are still handled in FIFO order.
If the function body returns normally the list of results are provided as the (successful) result of returned future. If the function throws an exception this results in a failed future. In the special case that the exception is in fact an unblessed "ARRAY" reference, this array is unpacked and used as-is for the "fail" result. If the exception is not such a reference, it is used as the first argument to "fail", in the category of "error".
$f->done( @result )
$f->fail( @{ $exception } )
$f->fail( $exception, error => )
$function->call( %params )
When not returning a future, the "on_result", "on_return" and "on_error" arguments give continuations to handle successful results or failure.
$on_result->( 'return', @values )
If the code threw an exception, or some other error occurred such as a closed connection or the process died, it is called as:
$on_result->( 'error', $exception_name )
$count = $function->workers
Returns the total number of worker processes available
$count = $function->workers_busy
Returns the number of worker processes that are currently busy
$count = $function->workers_idle
Returns the number of worker processes that are currently idle
my $divider = IO::Async::Function->new(
code => sub {
my ( $numerator, $divisor ) = @_;
$divisor == 0 and
die [ "Cannot divide by zero", div_zero => $numerator, $divisor ];
return $numerator / $divisor;
}
);