IO::Async::Function man page on Alpinelinux

Man page or keyword search:  
man Server   18016 pages
apropos Keyword Search (all sections)
Output format
Alpinelinux logo
[printable version]

IO::Async::Function(3)User Contributed Perl DocumentatioIO::Async::Function(3)

NAME
       "IO::Async::Function" - call a function asynchronously

SYNOPSIS
	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_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";
	   },
	);

	$loop->run;

DESCRIPTION
       This subclass of IO::Async::Notifier wraps a function body in a
       collection of worker processes, to allow it to execute independently of
       the main process.  The object acts as a proxy to the function, allowing
       invocations to be made by passing in arguments, and invoking a
       continuation in the main process when the function returns.

       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:

       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 a blocking OS syscall or library-level function needs to be
	   called, and no nonblocking or asynchronous version is supplied.
	   This is used by "IO::Async::Resolver".

       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.

PARAMETERS
       The following named parameters may be passed to "new" or "configure":

       code => CODE
	       The body of the function to execute.

       model => "spawn" | "thread"
	       Optional. Requests a specific "IO::Async::Routine" model. If
	       not supplied, leaves the default choice up to Routine.

       min_workers => INT
       max_workers => INT
	       The lower and upper bounds of worker processes to try to keep
	       running. The actual number running at any time will be kept
	       somewhere between these bounds according to load.

       max_worker_calls => INT
	       Optional. If provided, stop a worker process after it has
	       processed this number of calls. (New workers may be started to
	       replace stopped ones, within the bounds given above).

       idle_timeout => NUM
	       Optional. If provided, idle worker processes will be shut down
	       after this amount of time, if there are more than "min_workers"
	       of them.

       exit_on_die => BOOL
	       Optional boolean, controls what happens after the "code" throws
	       an exception. If missing or false, the worker will continue
	       running to process more requests. If true, the worker will be
	       shut down. A new worker might be constructed by the "call"
	       method to replace it, if necessary.

       setup => ARRAY
	       Optional array reference. Specifies the "setup" key to pass to
	       the underlying IO::Async::Process when setting up new worker
	       processes.

METHODS
   $function->start
       Start the worker processes

   $function->stop
       Stop the worker processes

   $function->restart
       Gracefully stop and restart all the worker processes.

   $function->call( %params )
       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:

       args => ARRAY
	       A reference to the array of arguments to pass to the code.

       on_result => CODE
	       A continuation 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 )

       on_return => CODE and on_error => CODE
	       An alternative to "on_result". Two continuations to use in
	       either of the circumstances given above. They will be called
	       directly, without the leading 'return' or 'error' value.

   $future = $function->call( %params )
       When returning a future, the "on_result", "on_return" and "on_error"
       continuations are optional.

   $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

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

AUTHOR
       Paul Evans <leonerd@leonerd.org.uk>

perl v5.18.2			  2014-05-14		IO::Async::Function(3)
[top]

List of man pages available for Alpinelinux

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net