1IO::Async::Routine(3) User Contributed Perl DocumentationIO::Async::Routine(3)
2
3
4

NAME

6       "IO::Async::Routine" - execute code in an independent sub-process or
7       thread
8

SYNOPSIS

10          use IO::Async::Routine;
11          use IO::Async::Channel;
12
13          use IO::Async::Loop;
14          my $loop = IO::Async::Loop->new;
15
16          my $nums_ch = IO::Async::Channel->new;
17          my $ret_ch  = IO::Async::Channel->new;
18
19          my $routine = IO::Async::Routine->new(
20             channels_in  => [ $nums_ch ],
21             channels_out => [ $ret_ch ],
22
23             code => sub {
24                my @nums = @{ $nums_ch->recv };
25                my $ret = 0; $ret += $_ for @nums;
26
27                # Can only send references
28                $ret_ch->send( \$ret );
29             },
30
31             on_finish => sub {
32                say "The routine aborted early - $_[-1]";
33                $loop->stop;
34             },
35          );
36
37          $loop->add( $routine );
38
39          $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
48          $loop->run;
49

DESCRIPTION

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
57       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
62       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
68   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
73       The "fork" model
74
75       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
81       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
86       The "thread" model
87
88       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
93       This model is only available on perls built to support threading.
94
95       The "spawn" model
96
97       Since version 0.79.
98
99       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
106       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
111       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

EVENTS

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
120   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
124       As the behaviour of these events differs per model, it may be more
125       convenient to use "on_return" and "on_die" instead.
126
127   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
132   on_die $exception
133       Invoked if the code block fails with an exception.
134

PARAMETERS

136       The following named parameters may be passed to "new" or "configure":
137
138   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
142       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
146   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
150   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
154   code => CODE
155       CODE reference to the body of the Routine, to execute once the channels
156       are set up.
157
158       When using the "spawn" model, this is not permitted; you must use
159       "module" and "func" instead.
160
161   module => STRING
162   func => STRING
163       Since version 0.79.
164
165       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
173          module::func( @channels_in, @channels_out )
174
175   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

METHODS

181   id
182          $id = $routine->id
183
184       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
188   model
189          $model = $routine->model
190
191       Returns the detachment model in use by the Routine.
192
193   kill
194          $routine->kill( $signal )
195
196       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
202   result_future
203          $f = $routine->result_future
204
205       Since version 0.75.
206
207       Returns a new "IO::Async::Future" which will complete with the eventual
208       return value or exception when the routine finishes.
209
210       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

AUTHOR

215       Paul Evans <leonerd@leonerd.org.uk>
216
217
218
219perl v5.36.0                      2023-01-20             IO::Async::Routine(3)
Impressum