NAME

IO::Async::DetachedCode - a class that allows a block of code to execute asynchronously in a detached child process

SYNOPSIS

Usually this object would be constructed indirectly, via an IO::Async::Set:

 use IO::Async::Set::...;
 my $set = IO::Async::Set::...

 $set->enable_childmanager;

 my $code = $set->detach_code(
    code => sub {
       my ( $number ) = @_;
       return is_prime( $number );
    }
 );

 $code->call
    args => [ 123454321 ],
    on_return => sub {
       my $isprime = shift;
       print "123454321 " . ( $isprime ? "is" : "is not" ) . " a prime number\n";
    },
    on_error => sub {
       print STDERR "Cannot determine if it's prime - $_[0]\n";
    },
 );

 $set->loop_forever;

It can also be used directly. In this case, extra effort must be taken to pass an IO::Async::Set object:

 my $set = IO::Async::Set::...

 my $code = IO::Async::DetachedCode->new(
    set => $set,
    code => sub { ... },
 );

DESCRIPTION

This module provides a class that allows a block of code to "detach" from the main process, and execute independently in its own child process. The object itself acts as a proxy to this code block, allowing arguments to be passed to it each time it is called, and returning results back to a callback function in the main process.

The object represents the code block itself, rather than one specific invocation of it. It can be called multiple times, by the call() method. Multiple outstanding invocations can be queued up; they will be executed in the order they were queued, and results returned in that order.

The default marshalling code can only cope with plain scalars or undef values; no references, objects, or IO handles may be passed to the function each time it is called. If references are required, code based on Storable may be used instead, to pass these. See the documentation on the marshaller parameter of new() method.

The IO::Async framework generally provides mechanisms for multiplexing IO tasks between different handles, so there aren't many occasions when such detached code is necessary. Two cases where this does become useful are:

1. When a large amount of computationally-intensive work needs to be performed (for example, the is_prime() test in the example in the SYNOPSIS).

2. When an OS or library-level function needs to be called, that will block, and no asynchronous version is supplied.

CONSTRUCTOR

$code = IO::Async::DetachedCode->new( %params )

This function returns a new instance of a IO::Async::DetachedCode object. The %params hash takes the following keys:

set => IO::Async::Set

A reference to an IO::Async::Set object. The set must have the child manager enabled.

code => CODE

A block of code to call in the child process. It will be invoked in list context each time the call() method is is called, passing in the arguments given. The result will be given to the on_result or on_return callback provided to the call() method.

stream => STRING: socket or pipe

Optional string, specifies which sort of stream will be used to attach to the child process. socket uses only one file descriptor in the parent process, but not all systems may be able to use it. If the system does not allow PF_UNIX socket pairs, then pipe can be used instead. This will use two file descriptors in the parent process, however.

If not supplied, the socket method is used.

marshaller => STRING: flat or storable

Optional string, specifies the way that call arguments and return values are marshalled over the stream that connects the child and parent processes. The flat method is small, simple and fast, but can only cope with strings or undef; cannot cope with any references. The storable method uses the Storable module to marshall arbitrary reference structures.

If not supplied, the flat method is used.

Since the code block will be called multiple times within the same child process, it must take care not to modify any global 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.

METHODS

$code->call( %params )

This method queues one invocation of the code block to be executed in the child process. The %params hash takes the following keys:

args => ARRAY

A reference to the array of arguments to pass to the code.

on_result => CODE

A callback that is invoked when the code has been executed. If the code returned normally, it is called as:

 $on_result->( 'return', @values )

If the code threw an exception, or some other error occured such as a closed connection or the process died, it is called as:

 $on_result->( 'error', $exception_name )

or

on_return => CODE and on_error => CODE

Two callbacks to use in either of the circumstances given above. They will be called directly, without the leading 'return' or 'error' value.

The args key must always be supplied. Either the on_result or both the on_return and on_error keys must also be supplied.

$code->shutdown

This method requests that the detached child process stops running. All pending calls to the code are finished with a 'shutdown' error, and the child process itself exits.

It is not normally necessary to call this method during normal exit of the containing program. It is only required if the detact code is to be dropped, and recreated in a different way.

TODO

• Allow other argument/return value marshalling code - perhaps an arbitrary object.

• Pooling of multiple child processes - perhaps even dynamic. Default one process, allow dynamic creation of more if it's busy.

• Fall back on a pipe pair if socketpair doesn't work.

BUGS

• The child process is not shut down, and the connecting socket or pipes not closed when the application using the DetachedCode drops its last reference. This is due to an internal reference being kept. A workaround for this is to make sure always to call the shutdown() method. A proper fix will be included in a later version.

NOTES

For the record, 123454321 is 11111 * 11111, a square number, and therefore not prime.

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>

cpanm IO::Async::Set

perl -MCPAN -e shell
install IO::Async::Set