.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" 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::Routine 3pm"
.TH IO::Async::Routine 3pm "2018-04-19" "perl v5.26.2" "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::Routine" \- execute code in an independent sub\-process or thread
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\& use IO::Async::Routine;
\& use IO::Async::Channel;
\&
\& use IO::Async::Loop;
\& my $loop = IO::Async::Loop\->new;
\&
\& my $nums_ch = IO::Async::Channel\->new;
\& my $ret_ch  = IO::Async::Channel\->new;
\&
\& my $routine = IO::Async::Routine\->new(
\&    channels_in  => [ $nums_ch ],
\&    channels_out => [ $ret_ch ],
\&
\&    code => sub {
\&       my @nums = @{ $nums_ch\->recv };
\&       my $ret = 0; $ret += $_ for @nums;
\&
\&       # Can only send references
\&       $ret_ch\->send( \e$ret );
\&    },
\&
\&    on_finish => sub {
\&       say "The routine aborted early \- $_[\-1]";
\&       $loop\->stop;
\&    },
\& );
\&
\& $loop\->add( $routine );
\&
\& $nums_ch\->send( [ 10, 20, 30 ] );
\& $ret_ch\->recv(
\&    on_recv => sub {
\&       my ( $ch, $totalref ) = @_;
\&       say "The total of 10, 20, 30 is: $$totalref";
\&       $loop\->stop;
\&    }
\& );
\&
\& $loop\->run;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This IO::Async::Notifier contains a body of code and executes it in a
sub-process or thread, allowing it to act independently of the main program.
Once set up, all communication with the code happens by values passed into or
out of the Routine via IO::Async::Channel objects.
.PP
A choice of detachment model is available, with options being a \f(CW\*(C`fork()\*(C'\fRed
child process, or a thread. In both cases the code contained within the
Routine is free to make blocking calls without stalling the rest of the
program. This makes it useful for using existing code which has no option not
to block within an IO::Async\-based program.
.PP
Code running inside a \f(CW\*(C`fork()\*(C'\fR\-based Routine runs within its own process; it
is isolated from the rest of the program in terms of memory, \s-1CPU\s0 time, and
other resources. Code running in a thread-based Routine however, shares memory
and other resources such as open filehandles with the main thread.
.PP
To create asynchronous wrappers of functions that return a value based only on
their arguments, and do not generally maintain state within the process it may
be more convenient to use an IO::Async::Function instead, which uses an
\&\f(CW\*(C`IO::Async::Routine\*(C'\fR to contain the body of the function and manages the
Channels itself.
.SH "EVENTS"
.IX Header "EVENTS"
.ie n .SS "on_finish $exitcode"
.el .SS "on_finish \f(CW$exitcode\fP"
.IX Subsection "on_finish $exitcode"
For \f(CW\*(C`fork()\*(C'\fR\-based Routines, this is invoked after the process has exited and
is passed the raw exitcode status.
.ie n .SS "on_finish $type, @result"
.el .SS "on_finish \f(CW$type\fP, \f(CW@result\fP"
.IX Subsection "on_finish $type, @result"
For thread-based Routines, this is invoked after the thread has returned from
its code block and is passed the \f(CW\*(C`on_joined\*(C'\fR result.
.PP
As the behaviour of these events differs per model, it may be more convenient
to use \f(CW\*(C`on_return\*(C'\fR and \f(CW\*(C`on_die\*(C'\fR instead.
.ie n .SS "on_return $result"
.el .SS "on_return \f(CW$result\fP"
.IX Subsection "on_return $result"
Invoked if the code block returns normally. Note that \f(CW\*(C`fork()\*(C'\fR\-based Routines
can only transport an integer result between 0 and 255, as this is the actual
\&\f(CW\*(C`exit()\*(C'\fR value.
.ie n .SS "on_die $exception"
.el .SS "on_die \f(CW$exception\fP"
.IX Subsection "on_die $exception"
Invoked if the code block fails with an exception.
.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:
.ie n .SS "model => ""fork"" | ""thread"""
.el .SS "model => ``fork'' | ``thread''"
.IX Subsection "model => fork | thread"
Optional. Defines how the routine will detach itself from the main process.
\&\f(CW\*(C`fork\*(C'\fR uses a child process detached using an IO::Async::Process.
\&\f(CW\*(C`thread\*(C'\fR uses a thread, and is only available on threaded Perls.
.PP
If the model is not specified, the environment variable
\&\f(CW\*(C`IO_ASYNC_ROUTINE_MODEL\*(C'\fR is used to pick a default. If that isn't defined,
\&\f(CW\*(C`fork\*(C'\fR is preferred if it is available, otherwise \f(CW\*(C`thread\*(C'\fR.
.SS "channels_in => \s-1ARRAY\s0 of IO::Async::Channel"
.IX Subsection "channels_in => ARRAY of IO::Async::Channel"
\&\s-1ARRAY\s0 reference of IO::Async::Channel objects to set up for passing values
in to the Routine.
.SS "channels_out => \s-1ARRAY\s0 of IO::Async::Channel"
.IX Subsection "channels_out => ARRAY of IO::Async::Channel"
\&\s-1ARRAY\s0 reference of IO::Async::Channel objects to set up for passing values
out of the Routine.
.SS "code => \s-1CODE\s0"
.IX Subsection "code => CODE"
\&\s-1CODE\s0 reference to the body of the Routine, to execute once the channels are
set up.
.SS "setup => \s-1ARRAY\s0"
.IX Subsection "setup => ARRAY"
Optional. For \f(CW\*(C`fork()\*(C'\fR\-based Routines, gives a reference to an array to pass
to the underlying \f(CW\*(C`Loop\*(C'\fR \f(CW\*(C`fork_child\*(C'\fR method. Ignored for thread-based
Routines.
.SH "METHODS"
.IX Header "METHODS"
.SS "id"
.IX Subsection "id"
.Vb 1
\&   $id = $routine\->id
.Ve
.PP
Returns an \s-1ID\s0 string that uniquely identifies the Routine out of all the
currently-running ones. (The \s-1ID\s0 of already-exited Routines may be reused,
however.)
.SS "model"
.IX Subsection "model"
.Vb 1
\&   $model = $routine\->model
.Ve
.PP
Returns the detachment model in use by the Routine.
.SS "kill"
.IX Subsection "kill"
.Vb 1
\&   $routine\->kill( $signal )
.Ve
.PP
Sends the specified signal to the routine code. This is either implemented by
\&\f(CW\*(C`CORE::kill()\*(C'\fR or \f(CW\*(C`threads::kill\*(C'\fR as required. Note that in the thread case
this has the usual limits of signal delivery to threads; namely, that it works
at the Perl interpreter level, and cannot actually interrupt blocking system
calls.
.SH "AUTHOR"
.IX Header "AUTHOR"
Paul Evans <leonerd@leonerd.org.uk>