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 Since version 0.79.
98 The code in this model runs within its own freshly-created process
100 running another copy of the perl interpreter. Similar to the "fork"
101 model it therefore has its own memory, CPU time, and other resources.
102 However, since it is started freshly rather than by cloning the main
103 process, it starts up in a clean state, without any shared resources
104 from its parent.
105 Since this model creates a new fresh process rather than sharing
107 existing state, it cannot use the "code" argument to specify the
108 routine body; it must instead use only the "module" and "func"
109 arguments.
110 In the current implementation this model requires exactly one input
112 channel and exactly one output channel; both must be present, and there
113 cannot be more than one of either.
114
116 on_finish $exitcode
117 For fork()-based Routines, this is invoked after the process has exited
118 and is passed the raw exitcode status.
119 on_finish $type, @result
121 For thread-based Routines, this is invoked after the thread has
122 returned from its code block and is passed the "on_joined" result.
123 As the behaviour of these events differs per model, it may be more
125 convenient to use "on_return" and "on_die" instead.
126 on_return $result
128 Invoked if the code block returns normally. Note that fork()-based
129 Routines can only transport an integer result between 0 and 255, as
130 this is the actual exit() value.
131 on_die $exception
133 Invoked if the code block fails with an exception.
134
136 The following named parameters may be passed to "new" or "configure":
137 model => "fork" | "thread" | "spawn"
139 Optional. Defines how the routine will detach itself from the main
140 process. See the "Models" section above for more detail.
141 If the model is not specified, the environment variable
143 "IO_ASYNC_ROUTINE_MODEL" is used to pick a default. If that isn't
144 defined, "fork" is preferred if it is available, otherwise "thread".
145 channels_in => ARRAY of IO::Async::Channel
147 ARRAY reference of IO::Async::Channel objects to set up for passing
148 values in to the Routine.
149 channels_out => ARRAY of IO::Async::Channel
151 ARRAY reference of IO::Async::Channel objects to set up for passing
152 values out of the Routine.
153 code => CODE
155 CODE reference to the body of the Routine, to execute once the channels
156 are set up.
157 When using the "spawn" model, this is not permitted; you must use
159 "module" and "func" instead.
160 module => STRING
162 func => STRING
163 Since version 0.79.
164 An alternative to the "code" argument, which names a module to load and
166 a function to call within it. "module" should give a perl module name
167 (i.e. "Some::Name", not a filename like Some/Name.pm), and "func"
168 should give the basename of a function within that module (i.e. without
169 the module name prefixed). It will be invoked as the main code body of
170 the object, and passed in a list of all the channels; first the input
171 ones then the output ones.
172 module::func( @channels_in, @channels_out )
174 setup => ARRAY
176 Optional. For fork()-based Routines, gives a reference to an array to
177 pass to the underlying "Loop" "fork_child" method. Ignored for thread-
178 based Routines.
179
181 id
182 $id = $routine->id
183 Returns an ID string that uniquely identifies the Routine out of all
185 the currently-running ones. (The ID of already-exited Routines may be
186 reused, however.)
187 model
189 $model = $routine->model
190 Returns the detachment model in use by the Routine.
192 kill
194 $routine->kill( $signal )
195 Sends the specified signal to the routine code. This is either
197 implemented by CORE::kill() or "threads::kill" as required. Note that
198 in the thread case this has the usual limits of signal delivery to
199 threads; namely, that it works at the Perl interpreter level, and
200 cannot actually interrupt blocking system calls.
201 result_future
203 $f = $routine->result_future
204 Since version 0.75.
206 Returns a new "IO::Async::Future" which will complete with the eventual
208 return value or exception when the routine finishes.
209 If the routine finishes with a successful result then this will be the
211 "done" result of the future. If the routine fails with an exception
212 then this will be the "fail" result.
213
215 Paul Evans <leonerd@leonerd.org.uk>
216perl v5.36.0 2023-01-20 IO::Async::Routine(3)