1IO::Async::Routine(3) User Contributed Perl DocumentationIO::Async::Routine(3)
2
6 "IO::Async::Routine" - execute code in an independent sub-process or
7 thread
8
10 use IO::Async::Routine;
11 use IO::Async::Channel;
12 use IO::Async::Loop;
14 my $loop = IO::Async::Loop->new;
15 my $nums_ch = IO::Async::Channel->new;
17 my $ret_ch = IO::Async::Channel->new;
18 my $routine = IO::Async::Routine->new(
20 channels_in => [ $nums_ch ],
21 channels_out => [ $ret_ch ],
22 code => sub {
24 my @nums = @{ $nums_ch->recv };
25 my $ret = 0; $ret += $_ for @nums;
26 # Can only send references
28 $ret_ch->send( \$ret );
29 },
30 on_finish => sub {
32 say "The routine aborted early - $_[-1]";
33 $loop->stop;
34 },
35 );
36 $loop->add( $routine );
38 $nums_ch->send( [ 10, 20, 30 ] );
40 $ret_ch->recv(
41 on_recv => sub {
42 my ( $ch, $totalref ) = @_;
43 say "The total of 10, 20, 30 is: $$totalref";
44 $loop->stop;
45 }
46 );
47 $loop->run;
49
51 This IO::Async::Notifier contains a body of code and executes it in a
52 sub-process or thread, allowing it to act independently of the main
53 program. Once set up, all communication with the code happens by
54 values passed into or out of the Routine via IO::Async::Channel
55 objects.
56 A choice of detachment model is available, with options being a
58 "fork()"ed child process, or a thread. In both cases the code contained
59 within the Routine is free to make blocking calls without stalling the
60 rest of the program. This makes it useful for using existing code which
61 has no option not to block within an IO::Async-based program.
62 Code running inside a "fork()"-based Routine runs within its own
64 process; it is isolated from the rest of the program in terms of
65 memory, CPU time, and other resources. Code running in a thread-based
66 Routine however, shares memory and other resources such as open
67 filehandles with the main thread.
68 To create asynchronous wrappers of functions that return a value based
70 only on their arguments, and do not generally maintain state within the
71 process it may be more convenient to use an IO::Async::Function
72 instead, which uses an "IO::Async::Routine" to contain the body of the
73 function and manages the Channels itself.
74
76 on_finish $exitcode
77 For "fork()"-based Routines, this is invoked after the process has
78 exited and is passed the raw exitcode status.
79 on_finish $type, @result
81 For thread-based Routines, this is invoked after the thread has
82 returned from its code block and is passed the "on_joined" result.
83 As the behaviour of these events differs per model, it may be more
85 convenient to use "on_return" and "on_die" instead.
86 on_return $result
88 Invoked if the code block returns normally. Note that "fork()"-based
89 Routines can only transport an integer result between 0 and 255, as
90 this is the actual "exit()" value.
91 on_die $exception
93 Invoked if the code block fails with an exception.
94
96 The following named parameters may be passed to "new" or "configure":
97 model => "fork" | "thread"
99 Optional. Defines how the routine will detach itself from the main
100 process. "fork" uses a child process detached using an
101 IO::Async::Process. "thread" uses a thread, and is only available on
102 threaded Perls.
103 If the model is not specified, the environment variable
105 "IO_ASYNC_ROUTINE_MODEL" is used to pick a default. If that isn't
106 defined, "fork" is preferred if it is available, otherwise "thread".
107 channels_in => ARRAY of IO::Async::Channel
109 ARRAY reference of IO::Async::Channel objects to set up for passing
110 values in to the Routine.
111 channels_out => ARRAY of IO::Async::Channel
113 ARRAY reference of IO::Async::Channel objects to set up for passing
114 values out of the Routine.
115 code => CODE
117 CODE reference to the body of the Routine, to execute once the channels
118 are set up.
119 setup => ARRAY
121 Optional. For "fork()"-based Routines, gives a reference to an array to
122 pass to the underlying "Loop" "fork_child" method. Ignored for thread-
123 based Routines.
124
126 id
127 $id = $routine->id
128 Returns an ID string that uniquely identifies the Routine out of all
130 the currently-running ones. (The ID of already-exited Routines may be
131 reused, however.)
132 model
134 $model = $routine->model
135 Returns the detachment model in use by the Routine.
137 kill
139 $routine->kill( $signal )
140 Sends the specified signal to the routine code. This is either
142 implemented by "CORE::kill()" or "threads::kill" as required. Note that
143 in the thread case this has the usual limits of signal delivery to
144 threads; namely, that it works at the Perl interpreter level, and
145 cannot actually interrupt blocking system calls.
146 result_future
148 $f = $routine->result_future
149 Since version 0.75.
151 Returns a new "IO::Async::Future" which will complete with the eventual
153 return value or exception when the routine finishes.
154 If the routine finishes with a successful result then this will be the
156 "done" result of the future. If the routine fails with an exception
157 then this will be the "fail" result.
158
160 Paul Evans <leonerd@leonerd.org.uk>
161perl v5.32.1 2021-01-27 IO::Async::Routine(3)