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 The code contained within the Routine is free to make blocking calls
58 without stalling the rest of the program. This makes it useful for
59 using existing code which has no option not to block within an
60 IO::Async-based program.
61 To create asynchronous wrappers of functions that return a value based
63 only on their arguments, and do not generally maintain state within the
64 process it may be more convenient to use an IO::Async::Function
65 instead, which uses an "IO::Async::Routine" to contain the body of the
66 function and manages the Channels itself.
67 Models
69 A choice of detachment model is available. Each has various advantages
70 and disadvantages. Not all of them may be available on a particular
71 system.
72 The "fork" model
74 The code in this model runs within its own process, created by calling
76 "fork()" from the main process. It is isolated from the rest of the
77 program in terms of memory, CPU time, and other resources. Because it
78 is started using "fork()", the initial process state is a clone of the
79 main process.
80 This model performs well on UNIX-like operating systems which possess a
82 true native "fork()" system call, but is not available on "MSWin32" for
83 example, because the operating system does not provide full fork-like
84 semantics.
85 The "thread" model
87 The code in this model runs inside a separate thread within the main
89 process. It therefore shares memory and other resources such as open
90 filehandles with the main thread. As with the "fork" model, the initial
91 thread state is cloned from the main controlling thread.
92 This model is only available on perls built to support threading.
94 The "spawn" model
96 The code in this model runs within its own freshly-created process
98 running another copy of the perl interpreter. Similar to the "fork"
99 model it therefore has its own memory, CPU time, and other resources.
100 However, since it is started freshly rather than by cloning the main
101 process, it starts up in a clean state, without any shared resources
102 from its parent.
103 Since this model creates a new fresh process rather than sharing
105 existing state, it cannot use the "code" argument to specify the
106 routine body; it must instead use only the "module" and "func"
107 arguments.
108 In the current implementation this model requires exactly one input
110 channel and exactly one output channel; both must be present, and there
111 cannot be more than one of either.
112 This model performs well on both UNIX and Windows-like operating
114 systems, because it does not need full fork semantics.
115
117 on_finish $exitcode
118 For "fork()"-based Routines, this is invoked after the process has
119 exited and is passed the raw exitcode status.
120 on_finish $type, @result
122 For thread-based Routines, this is invoked after the thread has
123 returned from its code block and is passed the "on_joined" result.
124 As the behaviour of these events differs per model, it may be more
126 convenient to use "on_return" and "on_die" instead.
127 on_return $result
129 Invoked if the code block returns normally. Note that "fork()"-based
130 Routines can only transport an integer result between 0 and 255, as
131 this is the actual "exit()" value.
132 on_die $exception
134 Invoked if the code block fails with an exception.
135
137 The following named parameters may be passed to "new" or "configure":
138 model => "fork" | "thread" | "spawn"
140 Optional. Defines how the routine will detach itself from the main
141 process. See the "Models" section above for more detail.
142 If the model is not specified, the environment variable
144 "IO_ASYNC_ROUTINE_MODEL" is used to pick a default. If that isn't
145 defined, "fork" is preferred if it is available, otherwise "thread".
146 channels_in => ARRAY of IO::Async::Channel
148 ARRAY reference of IO::Async::Channel objects to set up for passing
149 values in to the Routine.
150 channels_out => ARRAY of IO::Async::Channel
152 ARRAY reference of IO::Async::Channel objects to set up for passing
153 values out of the Routine.
154 code => CODE
156 CODE reference to the body of the Routine, to execute once the channels
157 are set up.
158 When using the "spawn" model, this is not permitted; you must use
160 "module" and "func" instead.
161 module => STRING
163 func => STRING
164 An alternative to the "code" argument, which names a module to load and
165 a function to call within it. "module" should give a perl module name
166 (i.e. "Some::Name", not a filename like Some/Name.pm), and "func"
167 should give the basename of a function within that module (i.e. without
168 the module name prefixed). It will be invoked as the main code body of
169 the object, and passed in a list of all the channels; first the input
170 ones then the output ones.
171 module::func( @channels_in, @channels_out )
173 setup => ARRAY
175 Optional. For "fork()"-based Routines, gives a reference to an array to
176 pass to the underlying "Loop" "fork_child" method. Ignored for thread-
177 based Routines.
178
180 id
181 $id = $routine->id
182 Returns an ID string that uniquely identifies the Routine out of all
184 the currently-running ones. (The ID of already-exited Routines may be
185 reused, however.)
186 model
188 $model = $routine->model
189 Returns the detachment model in use by the Routine.
191 kill
193 $routine->kill( $signal )
194 Sends the specified signal to the routine code. This is either
196 implemented by "CORE::kill()" or "threads::kill" as required. Note that
197 in the thread case this has the usual limits of signal delivery to
198 threads; namely, that it works at the Perl interpreter level, and
199 cannot actually interrupt blocking system calls.
200 result_future
202 $f = $routine->result_future
203 Since version 0.75.
205 Returns a new "IO::Async::Future" which will complete with the eventual
207 return value or exception when the routine finishes.
208 If the routine finishes with a successful result then this will be the
210 "done" result of the future. If the routine fails with an exception
211 then this will be the "fail" result.
212
214 Paul Evans <leonerd@leonerd.org.uk>
215perl v5.34.0 2021-08-08 IO::Async::Routine(3)