.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "IO::Async::Function 3pm" .TH IO::Async::Function 3pm "2016-12-27" "perl v5.24.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" "IO::Async::Function" \- call a function asynchronously .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& 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\en"; \& })\->on_fail( sub { \& print STDERR "Cannot determine if it\*(Aqs prime \- $_[0]\en"; \& })\->get; .Ve .SH "DESCRIPTION" .IX Header "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. .PP The object represents the function code itself, rather than one specific invocation of it. It can be called multiple times, by the \f(CW\*(C`call\*(C'\fR 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. .PP 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. .PP 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. .PP The IO::Async framework generally provides mechanisms for multiplexing \s-1IO\s0 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: .IP "1." 4 When a large amount of computationally-intensive work needs to be performed (for example, the \f(CW\*(C`is_prime\*(C'\fR test in the example in the \f(CW\*(C`SYNOPSIS\*(C'\fR). .IP "2." 4 When a blocking \s-1OS\s0 syscall or library-level function needs to be called, and no nonblocking or asynchronous version is supplied. This is used by IO::Async::Resolver. .PP This object is ideal for representing \*(L"pure\*(R" 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. .SH "PARAMETERS" .IX Header "PARAMETERS" The following named parameters may be passed to \f(CW\*(C`new\*(C'\fR or \f(CW\*(C`configure\*(C'\fR: .SS "code => \s-1CODE\s0" .IX Subsection "code => CODE" The body of the function to execute. .PP .Vb 1 \& @result = $code\->( @args ) .Ve .SS "init_code => \s-1CODE\s0" .IX Subsection "init_code => CODE" Optional. If defined, this is invoked exactly once in every child process or thread, after it is created, but before the first invocation of the function body itself. .PP .Vb 1 \& $init_code\->() .Ve .ie n .SS "model => ""fork"" | ""thread""" .el .SS "model => ``fork'' | ``thread''" .IX Subsection "model => fork | thread" Optional. Requests a specific IO::Async::Routine model. If not supplied, leaves the default choice up to Routine. .SS "min_workers => \s-1INT\s0" .IX Subsection "min_workers => INT" .SS "max_workers => \s-1INT\s0" .IX Subsection "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. .SS "max_worker_calls => \s-1INT\s0" .IX Subsection "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). .SS "idle_timeout => \s-1NUM\s0" .IX Subsection "idle_timeout => NUM" Optional. If provided, idle worker processes will be shut down after this amount of time, if there are more than \f(CW\*(C`min_workers\*(C'\fR of them. .SS "exit_on_die => \s-1BOOL\s0" .IX Subsection "exit_on_die => BOOL" Optional boolean, controls what happens after the \f(CW\*(C`code\*(C'\fR 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 \f(CW\*(C`call\*(C'\fR method to replace it, if necessary. .SS "setup => \s-1ARRAY\s0" .IX Subsection "setup => ARRAY" Optional array reference. Specifies the \f(CW\*(C`setup\*(C'\fR key to pass to the underlying IO::Async::Process when setting up new worker processes. .SH "METHODS" .IX Header "METHODS" The following methods documented with a trailing call to \f(CW\*(C`\->get\*(C'\fR return Future instances. .SS "start" .IX Subsection "start" .Vb 1 \& $function\->start .Ve .PP Start the worker processes .SS "stop" .IX Subsection "stop" .Vb 1 \& $function\->stop .Ve .PP Stop the worker processes .SS "restart" .IX Subsection "restart" .Vb 1 \& $function\->restart .Ve .PP Gracefully stop and restart all the worker processes. .SS "call" .IX Subsection "call" .Vb 1 \& @result = $function\->call( %params )\->get .Ve .PP 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. .PP 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. .PP The \f(CW%params\fR hash takes the following keys: .IP "args => \s-1ARRAY\s0" 8 .IX Item "args => ARRAY" A reference to the array of arguments to pass to the code. .PP 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 \f(CW\*(C`ARRAY\*(C'\fR reference, this array is unpacked and used as-is for the \f(CW\*(C`fail\*(C'\fR result. If the exception is not such a reference, it is used as the first argument to \f(CW\*(C`fail\*(C'\fR, in the category of \f(CW\*(C`error\*(C'\fR. .PP .Vb 1 \& $f\->done( @result ) \& \& $f\->fail( @{ $exception } ) \& $f\->fail( $exception, error => ) .Ve .SS "call (void)" .IX Subsection "call (void)" .Vb 1 \& $function\->call( %params ) .Ve .PP When not returning a future, the \f(CW\*(C`on_result\*(C'\fR, \f(CW\*(C`on_return\*(C'\fR and \f(CW\*(C`on_error\*(C'\fR arguments give continuations to handle successful results or failure. .IP "on_result => \s-1CODE\s0" 8 .IX Item "on_result => CODE" A continuation that is invoked when the code has been executed. If the code returned normally, it is called as: .Sp .Vb 1 \& $on_result\->( \*(Aqreturn\*(Aq, @values ) .Ve .Sp If the code threw an exception, or some other error occurred such as a closed connection or the process died, it is called as: .Sp .Vb 1 \& $on_result\->( \*(Aqerror\*(Aq, $exception_name ) .Ve .IP "on_return => \s-1CODE\s0 and on_error => \s-1CODE\s0" 8 .IX Item "on_return => CODE and on_error => CODE" An alternative to \f(CW\*(C`on_result\*(C'\fR. Two continuations to use in either of the circumstances given above. They will be called directly, without the leading \&'return' or 'error' value. .SS "workers" .IX Subsection "workers" .Vb 1 \& $count = $function\->workers .Ve .PP Returns the total number of worker processes available .SS "workers_busy" .IX Subsection "workers_busy" .Vb 1 \& $count = $function\->workers_busy .Ve .PP Returns the number of worker processes that are currently busy .SS "workers_idle" .IX Subsection "workers_idle" .Vb 1 \& $count = $function\->workers_idle .Ve .PP Returns the number of worker processes that are currently idle .SH "EXAMPLES" .IX Header "EXAMPLES" .SS "Extended Error Information on Failure" .IX Subsection "Extended Error Information on Failure" The array-unpacking form of exception indiciation allows the function body to more precicely control the resulting failure from the \f(CW\*(C`call\*(C'\fR future. .PP .Vb 5 \& 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; \& } \& ); .Ve .SH "NOTES" .IX Header "NOTES" For the record, 123454321 is 11111 * 11111, a square number, and therefore not prime. .SH "AUTHOR" .IX Header "AUTHOR" Paul Evans