-
-
08 Aug 2022 22:50:11 UTC
- Distribution: Async
- Module version: 0.14
- Source (raw)
- Browse (raw)
- Changes
- How to Contribute
- Repository
- Issues (0)
- Testers (287 / 1 / 0)
- Kwalitee
Bus factor: 1- 68.03% Coverage
- License: unrestricted
- Perl: v5.6.0
- Activity
24 month- Tools
- Download (10.18KB)
- MetaCPAN Explorer
- Permissions
- Subscribe to distribution
- Permalinks
- This version
- Latest version
and 1 contributors- Mark-Jason Dominus
- Dependencies
- none
- Reverse dependencies
- CPAN Testers List
- Dependency graph
- NAME
- SYNOPSIS
- DESCRIPTION
- INTERFACE
- WARNINGS FOR THE PROGRAMMER
- ERRORS
- EXAMPLE
- AUTHOR
- COPYRIGHT AND LICENSE
NAME
Async - Asynchronous evaluation of Perl code (with optional timeouts)
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 { $result = $proc->result; # The return value of the code } } # or: $result = $proc->result( 'force completion' ); # wait for it to finish
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 asynchronous computation.
INTERFACE
To check if the asynchronous computation is complete you can call the
ready()
method, which returns true if so, and false if it is still running.After the asynchronous computation is complete, you should call the
error()
method to make sure that everything went all right.error()
will returnundef
if the computation completed normally, and an error message otherwise.Data returned by the computation can be retrieved with the
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,result()
will return an undefined value.result()
takes an optional parameter,$force
. If$force
is true, then the calling process will wait until the asynchronous computation is complete before returning.AsyncTimeout
use Async; $proc = AsyncTimeout->new( sub { ... }, $timeout, $special );
AsyncTimeout
implements a version ofAsync
that has an automatic timeout. If the asynchronous computation does not complete before$timeout
seconds have elapsed, it is forcibly terminated and returns a special value$special
. The default special value is the string "Timed out\n".All the other methods for
AsyncTimeout
are exactly the same as forAsync
.AsyncData
use Async; $proc = AsyncData->new( sub { ... } );
AsyncData
is just likeAsync
except that instead of returning a string, the asynchronous computation may return any scalar value. If the scalar value is a reference, theresult()
method will yield a refernce to a copy of this data structure.The
AsyncData
module requires thatStorable
be installed.AsyncData::new
will die ifStorable
is unavailable.All the other methods for
AsyncData
are exactly the same as forAsync
.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
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.ERRORS
The errors that are reported by the
error()
mechanism are: those that are internal toAsync
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 error; that is the normal termination of the process. Any messages written to
STDERR
will go to the computation'sSTDERR
, which is normally inherited from the main program, and theresult()
will be the empty string.EXAMPLE
use Async; sub long_running_computation { # This function simulates a computation that takes a long time to run my ( $x ) = @_; sleep 5; return $x + 2; # Eureka! } # Main program: my $proc = Async->new( sub { long_running_computation(2) } ) or die; # The long-running computation is now executing. # while (1) { print "Main program: The time is now ", scalar( localtime ), "\n"; my $e; if ( $proc->ready ) { if ( $e = $proc->error ) { print "Something went wrong. The error was: $e\n"; } else { print "The result of the computation is: ", $proc->result, "\n"; } undef $proc; } # The result is not ready; we can go off and do something else here. sleep 1; # One thing we could do is to take nap. }
AUTHOR
Mark-Jason Dominus
COPYRIGHT AND LICENSE
Mark-Jason Dominus has dedicated the work to the Commons by waiving all of his or her rights to the work worldwide under copyright law and all related or neighboring legal rights he or she had in the work, to the extent allowable by law.
Works under CC0 do not require attribution. When citing the work, you should not imply endorsement by the author.
Module Install Instructions
To install Async, copy and paste the appropriate command in to your terminal.
cpanm Async
perl -MCPAN -e shell install Async
For more information on module installation, please visit the detailed CPAN module installation guide.