Async

 view release on metacpan or  search on metacpan

Async.pm  view on Meta::CPAN

	my $rc = $self->SUPER::result( @_ );
	return defined $rc ? Storable::thaw( $rc ) : $rc;
}

1;

__END__

=head1 NAME

Async - Asynchronous evaluation of Perl code (with optional timeouts)

=head1 SYNOPSIS

  my $proc = Async->new( sub { any perl code you want executed } );

  if ( $proc->ready ) {
    # the code has finished executing
    if ( $proc->error ) {
      # something went wrong
    } else {

Async.pm  view on Meta::CPAN

  }

  # or:
  $result = $proc->result( 'force completion' ); # wait for it to finish

=head1 DESCRIPTION

This module runs some code in a separate process and retrieves its
result. Since the code is running in a separate process, your main
program can continue with whatever it was doing while the separate
code is executing. This separate code is called an I<asynchronous
computation>.

=head1 INTERFACE

To check if the asynchronous computation is complete you can call
the C<ready()>
method, which returns true if so, and false if it is still running.

After the asynchronous computation is complete, you should call the
C<error()> method to make sure that everything went all right.
C<error()> will return C<undef> if the computation completed normally,
and an error message otherwise.

Data returned by the computation can be retrieved with the C<result()>
method. The data must be a single string; any non-string value
returned by the computation will be stringified. (See AsyncData below
for how to avoid this.) If the computation has not completed yet,
C<result()> will return an undefined value.

C<result()> takes an optional parameter, C<$force>. If C<$force> is
true, then the calling process will wait until the asynchronous
computation is complete before returning.

=head2 C<AsyncTimeout>

  use Async;
  $proc = AsyncTimeout->new( sub { ... }, $timeout, $special );

C<AsyncTimeout> implements a version of C<Async> that has an
automatic timeout. If the asynchronous computation does not complete
before C<$timeout> seconds have elapsed, it is forcibly terminated and
returns a special value C<$special>. The default special value is the
string "Timed out\n".

All the other methods for C<AsyncTimeout> are exactly the same as for
C<Async>.

=head2 C<AsyncData>

  use Async;
  $proc = AsyncData->new( sub { ... } );

C<AsyncData> is just like C<Async> except that instead of returning a
string, the asynchronous computation may return any scalar value. If
the scalar value is a reference, the C<result()> method will yield a
refernce to a copy of this data structure.

The C<AsyncData> module requires that C<Storable> be installed.
C<AsyncData::new> will die if C<Storable> is unavailable.

All the other methods for C<AsyncData> are exactly the same as for
C<Async>.

=head1 WARNINGS FOR THE PROGRAMMER

The asynchronous computation takes place in a separate process, so
nothing it does can affect the main program. For example, if it
modifies global variables, changes the current directory, opens and
closes filehandles, or calls C<die>, the parent process will be
unaware of these things. However, the asynchronous computation does
inherit the main program's file handles, so if it reads data from
files that the main program had open, that data will not be availble
to the main program; similarly the asynchronous computation can write
data to the same file as the main program if it inherits an open
filehandle for that file.

=head1 ERRORS

The errors that are reported by the C<error()> mechanism are: those that are internal to C<Async> itself:

  Couldn't make pipe: (reason)
  Couldn't fork: (reason)
  Read error: (reason)

If your asynchronous computation dies for any reason, that is not
considered to be an I<error>; that is the normal termination of the
process. Any messages written to C<STDERR> will go to the
computation's C<STDERR>, which is normally inherited from the main
program, and the C<result()> will be the empty string.

=head1 EXAMPLE

  use Async;
  sub long_running_computation {
    # This function simulates a computation that takes a long time to run

META.json  view on Meta::CPAN

{
   "abstract" : "Asynchronous evaluation of Perl code (with optional timeouts)",
   "author" : [
      "Mark-Jason Dominus"
   ],
   "dynamic_config" : 0,
   "generated_by" : "ExtUtils::MakeMaker version 7.34, CPAN::Meta::Converter version 2.150010",
   "license" : [
      "unrestricted"
   ],
   "meta-spec" : {
      "url" : "http://search.cpan.org/perldoc?CPAN::Meta::Spec",

META.yml  view on Meta::CPAN

---
abstract: 'Asynchronous evaluation of Perl code (with optional timeouts)'
author:
  - 'Mark-Jason Dominus'
build_requires:
  Test::More: '0'
dynamic_config: 0
generated_by: 'ExtUtils::MakeMaker version 7.34, CPAN::Meta::Converter version 2.150010'
license: unrestricted
meta-spec:
  url: http://module-build.sourceforge.net/META-spec-v1.4.html
  version: '1.4'

README  view on Meta::CPAN

Async

This module runs some code in a separate process and retrieves its
result. Since the code is running in a separate process, your main
program can continue with whatever it was doing while the separate code
is executing. This separate code is called an *asynchronous computation*.

INSTALLATION

This is a Perl module distribution. It should be installed with whichever
tool you use to manage your installation of Perl, e.g. any of

  cpanm .
  cpan  .
  cpanp -i .

t/error-read-blocking.t  view on Meta::CPAN

use Async;

my $proc = Async->new( sub { 'Hello, world!' } );
isa_ok $proc, 'Async';

ok $proc->ready(1), 'waiting until ready';

my $error = 'Read error: ' . do { local $! = EFAULT };
like $proc->error, qr/\A\Q$error\E/, $error;

ok $proc->ready, 'asynchronous process keeps ready';

t/error-read-polling.t  view on Meta::CPAN

for ( 1 .. 10 ) {
	last if $ready = $proc->ready;
	note 'next polling in 250 milliseconds';
	select undef, undef, undef, 0.25;
}
ok $ready, 'waiting until ready';

my $error = 'Read error: ' . do { local $! = EFAULT };
like $proc->error, qr/\A\Q$error\E/, $error;

ok $proc->ready, 'asynchronous process keeps ready';

t/read-multiple.t  view on Meta::CPAN

isa_ok $proc, 'Async';

is $proc->result, undef, 'async process is incomplete (no force completion requested)';

ok $proc->ready(1), 'waiting until ready';

is $proc->error, undef, 'no error encountered';

is $proc->result, $expected_greeting, 'the return value of the task';

ok $proc->ready, 'asynchronous process keeps ready';